Edit on GitHub

Expressions

Every AST node in SQLGlot is represented by a subclass of Expression.

This module contains the implementation of all supported Expression types. Additionally, it exposes a number of helper functions, which are mainly used to programmatically build SQL expressions, such as sqlglot.expressions.select.


   1"""
   2## Expressions
   3
   4Every AST node in SQLGlot is represented by a subclass of `Expression`.
   5
   6This module contains the implementation of all supported `Expression` types. Additionally,
   7it exposes a number of helper functions, which are mainly used to programmatically build
   8SQL expressions, such as `sqlglot.expressions.select`.
   9
  10----
  11"""
  12
  13from __future__ import annotations
  14
  15import datetime
  16import math
  17import numbers
  18import re
  19import typing as t
  20from collections import deque
  21from copy import deepcopy
  22from enum import auto
  23
  24from sqlglot.errors import ParseError
  25from sqlglot.helper import (
  26    AutoName,
  27    camel_to_snake_case,
  28    ensure_collection,
  29    seq_get,
  30    split_num_words,
  31    subclasses,
  32)
  33from sqlglot.tokens import Token
  34
  35if t.TYPE_CHECKING:
  36    from sqlglot.dialects.dialect import DialectType
  37
  38
  39class _Expression(type):
  40    def __new__(cls, clsname, bases, attrs):
  41        klass = super().__new__(cls, clsname, bases, attrs)
  42
  43        # When an Expression class is created, its key is automatically set to be
  44        # the lowercase version of the class' name.
  45        klass.key = clsname.lower()
  46
  47        # This is so that docstrings are not inherited in pdoc
  48        klass.__doc__ = klass.__doc__ or ""
  49
  50        return klass
  51
  52
  53class Expression(metaclass=_Expression):
  54    """
  55    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
  56    context, such as its child expressions, their names (arg keys), and whether a given child expression
  57    is optional or not.
  58
  59    Attributes:
  60        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
  61            and representing expressions as strings.
  62        arg_types: determines what arguments (child nodes) are supported by an expression. It
  63            maps arg keys to booleans that indicate whether the corresponding args are optional.
  64
  65    Example:
  66        >>> class Foo(Expression):
  67        ...     arg_types = {"this": True, "expression": False}
  68
  69        The above definition informs us that Foo is an Expression that requires an argument called
  70        "this" and may also optionally receive an argument called "expression".
  71
  72    Args:
  73        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  74        parent: a reference to the parent expression (or None, in case of root expressions).
  75        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
  76            uses to refer to it.
  77        comments: a list of comments that are associated with a given expression. This is used in
  78            order to preserve comments when transpiling SQL code.
  79        _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
  80            optimizer, in order to enable some transformations that require type information.
  81    """
  82
  83    key = "expression"
  84    arg_types = {"this": True}
  85    __slots__ = ("args", "parent", "arg_key", "comments", "_type")
  86
  87    def __init__(self, **args: t.Any):
  88        self.args: t.Dict[str, t.Any] = args
  89        self.parent: t.Optional[Expression] = None
  90        self.arg_key: t.Optional[str] = None
  91        self.comments: t.Optional[t.List[str]] = None
  92        self._type: t.Optional[DataType] = None
  93
  94        for arg_key, value in self.args.items():
  95            self._set_parent(arg_key, value)
  96
  97    def __eq__(self, other) -> bool:
  98        return type(self) is type(other) and _norm_args(self) == _norm_args(other)
  99
 100    def __hash__(self) -> int:
 101        return hash(
 102            (
 103                self.key,
 104                tuple(
 105                    (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items()
 106                ),
 107            )
 108        )
 109
 110    @property
 111    def this(self):
 112        """
 113        Retrieves the argument with key "this".
 114        """
 115        return self.args.get("this")
 116
 117    @property
 118    def expression(self):
 119        """
 120        Retrieves the argument with key "expression".
 121        """
 122        return self.args.get("expression")
 123
 124    @property
 125    def expressions(self):
 126        """
 127        Retrieves the argument with key "expressions".
 128        """
 129        return self.args.get("expressions") or []
 130
 131    def text(self, key) -> str:
 132        """
 133        Returns a textual representation of the argument corresponding to "key". This can only be used
 134        for args that are strings or leaf Expression instances, such as identifiers and literals.
 135        """
 136        field = self.args.get(key)
 137        if isinstance(field, str):
 138            return field
 139        if isinstance(field, (Identifier, Literal, Var)):
 140            return field.this
 141        if isinstance(field, (Star, Null)):
 142            return field.name
 143        return ""
 144
 145    @property
 146    def is_string(self) -> bool:
 147        """
 148        Checks whether a Literal expression is a string.
 149        """
 150        return isinstance(self, Literal) and self.args["is_string"]
 151
 152    @property
 153    def is_number(self) -> bool:
 154        """
 155        Checks whether a Literal expression is a number.
 156        """
 157        return isinstance(self, Literal) and not self.args["is_string"]
 158
 159    @property
 160    def is_int(self) -> bool:
 161        """
 162        Checks whether a Literal expression is an integer.
 163        """
 164        if self.is_number:
 165            try:
 166                int(self.name)
 167                return True
 168            except ValueError:
 169                pass
 170        return False
 171
 172    @property
 173    def is_star(self) -> bool:
 174        """Checks whether an expression is a star."""
 175        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
 176
 177    @property
 178    def alias(self) -> str:
 179        """
 180        Returns the alias of the expression, or an empty string if it's not aliased.
 181        """
 182        if isinstance(self.args.get("alias"), TableAlias):
 183            return self.args["alias"].name
 184        return self.text("alias")
 185
 186    @property
 187    def name(self) -> str:
 188        return self.text("this")
 189
 190    @property
 191    def alias_or_name(self):
 192        return self.alias or self.name
 193
 194    @property
 195    def output_name(self):
 196        """
 197        Name of the output column if this expression is a selection.
 198
 199        If the Expression has no output name, an empty string is returned.
 200
 201        Example:
 202            >>> from sqlglot import parse_one
 203            >>> parse_one("SELECT a").expressions[0].output_name
 204            'a'
 205            >>> parse_one("SELECT b AS c").expressions[0].output_name
 206            'c'
 207            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
 208            ''
 209        """
 210        return ""
 211
 212    @property
 213    def type(self) -> t.Optional[DataType]:
 214        return self._type
 215
 216    @type.setter
 217    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
 218        if dtype and not isinstance(dtype, DataType):
 219            dtype = DataType.build(dtype)
 220        self._type = dtype  # type: ignore
 221
 222    def __deepcopy__(self, memo):
 223        copy = self.__class__(**deepcopy(self.args))
 224        copy.comments = self.comments
 225        copy.type = self.type
 226        return copy
 227
 228    def copy(self):
 229        """
 230        Returns a deep copy of the expression.
 231        """
 232        new = deepcopy(self)
 233        new.parent = self.parent
 234        for item, parent, _ in new.bfs():
 235            if isinstance(item, Expression) and parent:
 236                item.parent = parent
 237        return new
 238
 239    def append(self, arg_key, value):
 240        """
 241        Appends value to arg_key if it's a list or sets it as a new list.
 242
 243        Args:
 244            arg_key (str): name of the list expression arg
 245            value (Any): value to append to the list
 246        """
 247        if not isinstance(self.args.get(arg_key), list):
 248            self.args[arg_key] = []
 249        self.args[arg_key].append(value)
 250        self._set_parent(arg_key, value)
 251
 252    def set(self, arg_key, value):
 253        """
 254        Sets `arg_key` to `value`.
 255
 256        Args:
 257            arg_key (str): name of the expression arg.
 258            value: value to set the arg to.
 259        """
 260        self.args[arg_key] = value
 261        self._set_parent(arg_key, value)
 262
 263    def _set_parent(self, arg_key, value):
 264        if isinstance(value, Expression):
 265            value.parent = self
 266            value.arg_key = arg_key
 267        elif isinstance(value, list):
 268            for v in value:
 269                if isinstance(v, Expression):
 270                    v.parent = self
 271                    v.arg_key = arg_key
 272
 273    @property
 274    def depth(self):
 275        """
 276        Returns the depth of this tree.
 277        """
 278        if self.parent:
 279            return self.parent.depth + 1
 280        return 0
 281
 282    def find(self, *expression_types, bfs=True):
 283        """
 284        Returns the first node in this tree which matches at least one of
 285        the specified types.
 286
 287        Args:
 288            expression_types (type): the expression type(s) to match.
 289
 290        Returns:
 291            The node which matches the criteria or None if no such node was found.
 292        """
 293        return next(self.find_all(*expression_types, bfs=bfs), None)
 294
 295    def find_all(self, *expression_types, bfs=True):
 296        """
 297        Returns a generator object which visits all nodes in this tree and only
 298        yields those that match at least one of the specified expression types.
 299
 300        Args:
 301            expression_types (type): the expression type(s) to match.
 302
 303        Returns:
 304            The generator object.
 305        """
 306        for expression, _, _ in self.walk(bfs=bfs):
 307            if isinstance(expression, expression_types):
 308                yield expression
 309
 310    def find_ancestor(self, *expression_types):
 311        """
 312        Returns a nearest parent matching expression_types.
 313
 314        Args:
 315            expression_types (type): the expression type(s) to match.
 316
 317        Returns:
 318            The parent node.
 319        """
 320        ancestor = self.parent
 321        while ancestor and not isinstance(ancestor, expression_types):
 322            ancestor = ancestor.parent
 323        return ancestor
 324
 325    @property
 326    def parent_select(self):
 327        """
 328        Returns the parent select statement.
 329        """
 330        return self.find_ancestor(Select)
 331
 332    def walk(self, bfs=True, prune=None):
 333        """
 334        Returns a generator object which visits all nodes in this tree.
 335
 336        Args:
 337            bfs (bool): if set to True the BFS traversal order will be applied,
 338                otherwise the DFS traversal will be used instead.
 339            prune ((node, parent, arg_key) -> bool): callable that returns True if
 340                the generator should stop traversing this branch of the tree.
 341
 342        Returns:
 343            the generator object.
 344        """
 345        if bfs:
 346            yield from self.bfs(prune=prune)
 347        else:
 348            yield from self.dfs(prune=prune)
 349
 350    def dfs(self, parent=None, key=None, prune=None):
 351        """
 352        Returns a generator object which visits all nodes in this tree in
 353        the DFS (Depth-first) order.
 354
 355        Returns:
 356            The generator object.
 357        """
 358        parent = parent or self.parent
 359        yield self, parent, key
 360        if prune and prune(self, parent, key):
 361            return
 362
 363        for k, v in self.args.items():
 364            for node in ensure_collection(v):
 365                if isinstance(node, Expression):
 366                    yield from node.dfs(self, k, prune)
 367
 368    def bfs(self, prune=None):
 369        """
 370        Returns a generator object which visits all nodes in this tree in
 371        the BFS (Breadth-first) order.
 372
 373        Returns:
 374            The generator object.
 375        """
 376        queue = deque([(self, self.parent, None)])
 377
 378        while queue:
 379            item, parent, key = queue.popleft()
 380
 381            yield item, parent, key
 382            if prune and prune(item, parent, key):
 383                continue
 384
 385            if isinstance(item, Expression):
 386                for k, v in item.args.items():
 387                    for node in ensure_collection(v):
 388                        if isinstance(node, Expression):
 389                            queue.append((node, item, k))
 390
 391    def unnest(self):
 392        """
 393        Returns the first non parenthesis child or self.
 394        """
 395        expression = self
 396        while isinstance(expression, Paren):
 397            expression = expression.this
 398        return expression
 399
 400    def unalias(self):
 401        """
 402        Returns the inner expression if this is an Alias.
 403        """
 404        if isinstance(self, Alias):
 405            return self.this
 406        return self
 407
 408    def unnest_operands(self):
 409        """
 410        Returns unnested operands as a tuple.
 411        """
 412        return tuple(arg.unnest() for arg in self.args.values() if arg)
 413
 414    def flatten(self, unnest=True):
 415        """
 416        Returns a generator which yields child nodes who's parents are the same class.
 417
 418        A AND B AND C -> [A, B, C]
 419        """
 420        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
 421            if not isinstance(node, self.__class__):
 422                yield node.unnest() if unnest else node
 423
 424    def __str__(self):
 425        return self.sql()
 426
 427    def __repr__(self):
 428        return self._to_s()
 429
 430    def sql(self, dialect: DialectType = None, **opts) -> str:
 431        """
 432        Returns SQL string representation of this tree.
 433
 434        Args:
 435            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
 436            opts: other `sqlglot.generator.Generator` options.
 437
 438        Returns:
 439            The SQL string.
 440        """
 441        from sqlglot.dialects import Dialect
 442
 443        return Dialect.get_or_raise(dialect)().generate(self, **opts)
 444
 445    def _to_s(self, hide_missing: bool = True, level: int = 0) -> str:
 446        indent = "" if not level else "\n"
 447        indent += "".join(["  "] * level)
 448        left = f"({self.key.upper()} "
 449
 450        args: t.Dict[str, t.Any] = {
 451            k: ", ".join(
 452                v._to_s(hide_missing=hide_missing, level=level + 1)
 453                if hasattr(v, "_to_s")
 454                else str(v)
 455                for v in ensure_collection(vs)
 456                if v is not None
 457            )
 458            for k, vs in self.args.items()
 459        }
 460        args["comments"] = self.comments
 461        args["type"] = self.type
 462        args = {k: v for k, v in args.items() if v or not hide_missing}
 463
 464        right = ", ".join(f"{k}: {v}" for k, v in args.items())
 465        right += ")"
 466
 467        return indent + left + right
 468
 469    def transform(self, fun, *args, copy=True, **kwargs):
 470        """
 471        Recursively visits all tree nodes (excluding already transformed ones)
 472        and applies the given transformation function to each node.
 473
 474        Args:
 475            fun (function): a function which takes a node as an argument and returns a
 476                new transformed node or the same node without modifications. If the function
 477                returns None, then the corresponding node will be removed from the syntax tree.
 478            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
 479                modified in place.
 480
 481        Returns:
 482            The transformed tree.
 483        """
 484        node = self.copy() if copy else self
 485        new_node = fun(node, *args, **kwargs)
 486
 487        if new_node is None or not isinstance(new_node, Expression):
 488            return new_node
 489        if new_node is not node:
 490            new_node.parent = node.parent
 491            return new_node
 492
 493        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
 494        return new_node
 495
 496    def replace(self, expression):
 497        """
 498        Swap out this expression with a new expression.
 499
 500        For example::
 501
 502            >>> tree = Select().select("x").from_("tbl")
 503            >>> tree.find(Column).replace(Column(this="y"))
 504            (COLUMN this: y)
 505            >>> tree.sql()
 506            'SELECT y FROM tbl'
 507
 508        Args:
 509            expression (Expression|None): new node
 510
 511        Returns:
 512            The new expression or expressions.
 513        """
 514        if not self.parent:
 515            return expression
 516
 517        parent = self.parent
 518        self.parent = None
 519
 520        replace_children(parent, lambda child: expression if child is self else child)
 521        return expression
 522
 523    def pop(self):
 524        """
 525        Remove this expression from its AST.
 526        """
 527        self.replace(None)
 528
 529    def assert_is(self, type_):
 530        """
 531        Assert that this `Expression` is an instance of `type_`.
 532
 533        If it is NOT an instance of `type_`, this raises an assertion error.
 534        Otherwise, this returns this expression.
 535
 536        Examples:
 537            This is useful for type security in chained expressions:
 538
 539            >>> import sqlglot
 540            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
 541            'SELECT x, z FROM y'
 542        """
 543        assert isinstance(self, type_)
 544        return self
 545
 546    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
 547        """
 548        Checks if this expression is valid (e.g. all mandatory args are set).
 549
 550        Args:
 551            args: a sequence of values that were used to instantiate a Func expression. This is used
 552                to check that the provided arguments don't exceed the function argument limit.
 553
 554        Returns:
 555            A list of error messages for all possible errors that were found.
 556        """
 557        errors: t.List[str] = []
 558
 559        for k in self.args:
 560            if k not in self.arg_types:
 561                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
 562        for k, mandatory in self.arg_types.items():
 563            v = self.args.get(k)
 564            if mandatory and (v is None or (isinstance(v, list) and not v)):
 565                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
 566
 567        if (
 568            args
 569            and isinstance(self, Func)
 570            and len(args) > len(self.arg_types)
 571            and not self.is_var_len_args
 572        ):
 573            errors.append(
 574                f"The number of provided arguments ({len(args)}) is greater than "
 575                f"the maximum number of supported arguments ({len(self.arg_types)})"
 576            )
 577
 578        return errors
 579
 580    def dump(self):
 581        """
 582        Dump this Expression to a JSON-serializable dict.
 583        """
 584        from sqlglot.serde import dump
 585
 586        return dump(self)
 587
 588    @classmethod
 589    def load(cls, obj):
 590        """
 591        Load a dict (as returned by `Expression.dump`) into an Expression instance.
 592        """
 593        from sqlglot.serde import load
 594
 595        return load(obj)
 596
 597
 598IntoType = t.Union[
 599    str,
 600    t.Type[Expression],
 601    t.Collection[t.Union[str, t.Type[Expression]]],
 602]
 603
 604
 605class Condition(Expression):
 606    def and_(self, *expressions, dialect=None, **opts):
 607        """
 608        AND this condition with one or multiple expressions.
 609
 610        Example:
 611            >>> condition("x=1").and_("y=1").sql()
 612            'x = 1 AND y = 1'
 613
 614        Args:
 615            *expressions (str | Expression): the SQL code strings to parse.
 616                If an `Expression` instance is passed, it will be used as-is.
 617            dialect (str): the dialect used to parse the input expression.
 618            opts (kwargs): other options to use to parse the input expressions.
 619
 620        Returns:
 621            And: the new condition.
 622        """
 623        return and_(self, *expressions, dialect=dialect, **opts)
 624
 625    def or_(self, *expressions, dialect=None, **opts):
 626        """
 627        OR this condition with one or multiple expressions.
 628
 629        Example:
 630            >>> condition("x=1").or_("y=1").sql()
 631            'x = 1 OR y = 1'
 632
 633        Args:
 634            *expressions (str | Expression): the SQL code strings to parse.
 635                If an `Expression` instance is passed, it will be used as-is.
 636            dialect (str): the dialect used to parse the input expression.
 637            opts (kwargs): other options to use to parse the input expressions.
 638
 639        Returns:
 640            Or: the new condition.
 641        """
 642        return or_(self, *expressions, dialect=dialect, **opts)
 643
 644    def not_(self):
 645        """
 646        Wrap this condition with NOT.
 647
 648        Example:
 649            >>> condition("x=1").not_().sql()
 650            'NOT x = 1'
 651
 652        Returns:
 653            Not: the new condition.
 654        """
 655        return not_(self)
 656
 657
 658class Predicate(Condition):
 659    """Relationships like x = y, x > 1, x >= y."""
 660
 661
 662class DerivedTable(Expression):
 663    @property
 664    def alias_column_names(self):
 665        table_alias = self.args.get("alias")
 666        if not table_alias:
 667            return []
 668        column_list = table_alias.assert_is(TableAlias).args.get("columns") or []
 669        return [c.name for c in column_list]
 670
 671    @property
 672    def selects(self):
 673        alias = self.args.get("alias")
 674
 675        if alias:
 676            return alias.columns
 677        return []
 678
 679    @property
 680    def named_selects(self):
 681        return [select.output_name for select in self.selects]
 682
 683
 684class Unionable(Expression):
 685    def union(self, expression, distinct=True, dialect=None, **opts):
 686        """
 687        Builds a UNION expression.
 688
 689        Example:
 690            >>> import sqlglot
 691            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
 692            'SELECT * FROM foo UNION SELECT * FROM bla'
 693
 694        Args:
 695            expression (str | Expression): the SQL code string.
 696                If an `Expression` instance is passed, it will be used as-is.
 697            distinct (bool): set the DISTINCT flag if and only if this is true.
 698            dialect (str): the dialect used to parse the input expression.
 699            opts (kwargs): other options to use to parse the input expressions.
 700        Returns:
 701            Union: the Union expression.
 702        """
 703        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 704
 705    def intersect(self, expression, distinct=True, dialect=None, **opts):
 706        """
 707        Builds an INTERSECT expression.
 708
 709        Example:
 710            >>> import sqlglot
 711            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
 712            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
 713
 714        Args:
 715            expression (str | Expression): the SQL code string.
 716                If an `Expression` instance is passed, it will be used as-is.
 717            distinct (bool): set the DISTINCT flag if and only if this is true.
 718            dialect (str): the dialect used to parse the input expression.
 719            opts (kwargs): other options to use to parse the input expressions.
 720        Returns:
 721            Intersect: the Intersect expression
 722        """
 723        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 724
 725    def except_(self, expression, distinct=True, dialect=None, **opts):
 726        """
 727        Builds an EXCEPT expression.
 728
 729        Example:
 730            >>> import sqlglot
 731            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
 732            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
 733
 734        Args:
 735            expression (str | Expression): the SQL code string.
 736                If an `Expression` instance is passed, it will be used as-is.
 737            distinct (bool): set the DISTINCT flag if and only if this is true.
 738            dialect (str): the dialect used to parse the input expression.
 739            opts (kwargs): other options to use to parse the input expressions.
 740        Returns:
 741            Except: the Except expression
 742        """
 743        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 744
 745
 746class UDTF(DerivedTable, Unionable):
 747    pass
 748
 749
 750class Cache(Expression):
 751    arg_types = {
 752        "with": False,
 753        "this": True,
 754        "lazy": False,
 755        "options": False,
 756        "expression": False,
 757    }
 758
 759
 760class Uncache(Expression):
 761    arg_types = {"this": True, "exists": False}
 762
 763
 764class Create(Expression):
 765    arg_types = {
 766        "with": False,
 767        "this": True,
 768        "kind": True,
 769        "expression": False,
 770        "set": False,
 771        "multiset": False,
 772        "global_temporary": False,
 773        "volatile": False,
 774        "exists": False,
 775        "properties": False,
 776        "temporary": False,
 777        "transient": False,
 778        "external": False,
 779        "replace": False,
 780        "unique": False,
 781        "materialized": False,
 782        "data": False,
 783        "statistics": False,
 784        "no_primary_index": False,
 785        "indexes": False,
 786        "no_schema_binding": False,
 787        "begin": False,
 788    }
 789
 790
 791class Describe(Expression):
 792    arg_types = {"this": True, "kind": False}
 793
 794
 795class Set(Expression):
 796    arg_types = {"expressions": True}
 797
 798
 799class SetItem(Expression):
 800    arg_types = {
 801        "this": False,
 802        "expressions": False,
 803        "kind": False,
 804        "collate": False,  # MySQL SET NAMES statement
 805        "global": False,
 806    }
 807
 808
 809class Show(Expression):
 810    arg_types = {
 811        "this": True,
 812        "target": False,
 813        "offset": False,
 814        "limit": False,
 815        "like": False,
 816        "where": False,
 817        "db": False,
 818        "full": False,
 819        "mutex": False,
 820        "query": False,
 821        "channel": False,
 822        "global": False,
 823        "log": False,
 824        "position": False,
 825        "types": False,
 826    }
 827
 828
 829class UserDefinedFunction(Expression):
 830    arg_types = {"this": True, "expressions": False, "wrapped": False}
 831
 832
 833class CharacterSet(Expression):
 834    arg_types = {"this": True, "default": False}
 835
 836
 837class With(Expression):
 838    arg_types = {"expressions": True, "recursive": False}
 839
 840    @property
 841    def recursive(self) -> bool:
 842        return bool(self.args.get("recursive"))
 843
 844
 845class WithinGroup(Expression):
 846    arg_types = {"this": True, "expression": False}
 847
 848
 849class CTE(DerivedTable):
 850    arg_types = {"this": True, "alias": True}
 851
 852
 853class TableAlias(Expression):
 854    arg_types = {"this": False, "columns": False}
 855
 856    @property
 857    def columns(self):
 858        return self.args.get("columns") or []
 859
 860
 861class BitString(Condition):
 862    pass
 863
 864
 865class HexString(Condition):
 866    pass
 867
 868
 869class ByteString(Condition):
 870    pass
 871
 872
 873class Column(Condition):
 874    arg_types = {"this": True, "table": False, "db": False, "catalog": False}
 875
 876    @property
 877    def table(self) -> str:
 878        return self.text("table")
 879
 880    @property
 881    def db(self) -> str:
 882        return self.text("db")
 883
 884    @property
 885    def catalog(self) -> str:
 886        return self.text("catalog")
 887
 888    @property
 889    def output_name(self) -> str:
 890        return self.name
 891
 892
 893class ColumnDef(Expression):
 894    arg_types = {
 895        "this": True,
 896        "kind": False,
 897        "constraints": False,
 898        "exists": False,
 899    }
 900
 901
 902class AlterColumn(Expression):
 903    arg_types = {
 904        "this": True,
 905        "dtype": False,
 906        "collate": False,
 907        "using": False,
 908        "default": False,
 909        "drop": False,
 910    }
 911
 912
 913class RenameTable(Expression):
 914    pass
 915
 916
 917class ColumnConstraint(Expression):
 918    arg_types = {"this": False, "kind": True}
 919
 920
 921class ColumnConstraintKind(Expression):
 922    pass
 923
 924
 925class AutoIncrementColumnConstraint(ColumnConstraintKind):
 926    pass
 927
 928
 929class CaseSpecificColumnConstraint(ColumnConstraintKind):
 930    arg_types = {"not_": True}
 931
 932
 933class CharacterSetColumnConstraint(ColumnConstraintKind):
 934    arg_types = {"this": True}
 935
 936
 937class CheckColumnConstraint(ColumnConstraintKind):
 938    pass
 939
 940
 941class CollateColumnConstraint(ColumnConstraintKind):
 942    pass
 943
 944
 945class CommentColumnConstraint(ColumnConstraintKind):
 946    pass
 947
 948
 949class CompressColumnConstraint(ColumnConstraintKind):
 950    pass
 951
 952
 953class DateFormatColumnConstraint(ColumnConstraintKind):
 954    arg_types = {"this": True}
 955
 956
 957class DefaultColumnConstraint(ColumnConstraintKind):
 958    pass
 959
 960
 961class EncodeColumnConstraint(ColumnConstraintKind):
 962    pass
 963
 964
 965class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
 966    # this: True -> ALWAYS, this: False -> BY DEFAULT
 967    arg_types = {
 968        "this": False,
 969        "start": False,
 970        "increment": False,
 971        "minvalue": False,
 972        "maxvalue": False,
 973        "cycle": False,
 974    }
 975
 976
 977class InlineLengthColumnConstraint(ColumnConstraintKind):
 978    pass
 979
 980
 981class NotNullColumnConstraint(ColumnConstraintKind):
 982    arg_types = {"allow_null": False}
 983
 984
 985class PrimaryKeyColumnConstraint(ColumnConstraintKind):
 986    arg_types = {"desc": False}
 987
 988
 989class TitleColumnConstraint(ColumnConstraintKind):
 990    pass
 991
 992
 993class UniqueColumnConstraint(ColumnConstraintKind):
 994    arg_types: t.Dict[str, t.Any] = {}
 995
 996
 997class UppercaseColumnConstraint(ColumnConstraintKind):
 998    arg_types: t.Dict[str, t.Any] = {}
 999
1000
1001class PathColumnConstraint(ColumnConstraintKind):
1002    pass
1003
1004
1005class Constraint(Expression):
1006    arg_types = {"this": True, "expressions": True}
1007
1008
1009class Delete(Expression):
1010    arg_types = {"with": False, "this": False, "using": False, "where": False}
1011
1012
1013class Drop(Expression):
1014    arg_types = {
1015        "this": False,
1016        "kind": False,
1017        "exists": False,
1018        "temporary": False,
1019        "materialized": False,
1020        "cascade": False,
1021    }
1022
1023
1024class Filter(Expression):
1025    arg_types = {"this": True, "expression": True}
1026
1027
1028class Check(Expression):
1029    pass
1030
1031
1032class Directory(Expression):
1033    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1034    arg_types = {"this": True, "local": False, "row_format": False}
1035
1036
1037class ForeignKey(Expression):
1038    arg_types = {
1039        "expressions": True,
1040        "reference": False,
1041        "delete": False,
1042        "update": False,
1043    }
1044
1045
1046class PrimaryKey(Expression):
1047    arg_types = {"expressions": True, "options": False}
1048
1049
1050class Unique(Expression):
1051    arg_types = {"expressions": True}
1052
1053
1054# https://www.postgresql.org/docs/9.1/sql-selectinto.html
1055# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples
1056class Into(Expression):
1057    arg_types = {"this": True, "temporary": False, "unlogged": False}
1058
1059
1060class From(Expression):
1061    arg_types = {"expressions": True}
1062
1063
1064class Having(Expression):
1065    pass
1066
1067
1068class Hint(Expression):
1069    arg_types = {"expressions": True}
1070
1071
1072class JoinHint(Expression):
1073    arg_types = {"this": True, "expressions": True}
1074
1075
1076class Identifier(Expression):
1077    arg_types = {"this": True, "quoted": False}
1078
1079    @property
1080    def quoted(self):
1081        return bool(self.args.get("quoted"))
1082
1083    def __eq__(self, other):
1084        return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this)
1085
1086    def __hash__(self):
1087        return hash((self.key, self.this.lower()))
1088
1089    @property
1090    def output_name(self):
1091        return self.name
1092
1093
1094class Index(Expression):
1095    arg_types = {
1096        "this": False,
1097        "table": False,
1098        "where": False,
1099        "columns": False,
1100        "unique": False,
1101        "primary": False,
1102        "amp": False,  # teradata
1103    }
1104
1105
1106class Insert(Expression):
1107    arg_types = {
1108        "with": False,
1109        "this": True,
1110        "expression": False,
1111        "overwrite": False,
1112        "exists": False,
1113        "partition": False,
1114        "alternative": False,
1115    }
1116
1117
1118# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html
1119class Introducer(Expression):
1120    arg_types = {"this": True, "expression": True}
1121
1122
1123# national char, like n'utf8'
1124class National(Expression):
1125    pass
1126
1127
1128class LoadData(Expression):
1129    arg_types = {
1130        "this": True,
1131        "local": False,
1132        "overwrite": False,
1133        "inpath": True,
1134        "partition": False,
1135        "input_format": False,
1136        "serde": False,
1137    }
1138
1139
1140class Partition(Expression):
1141    arg_types = {"expressions": True}
1142
1143
1144class Fetch(Expression):
1145    arg_types = {"direction": False, "count": False}
1146
1147
1148class Group(Expression):
1149    arg_types = {
1150        "expressions": False,
1151        "grouping_sets": False,
1152        "cube": False,
1153        "rollup": False,
1154    }
1155
1156
1157class Lambda(Expression):
1158    arg_types = {"this": True, "expressions": True}
1159
1160
1161class Limit(Expression):
1162    arg_types = {"this": False, "expression": True}
1163
1164
1165class Literal(Condition):
1166    arg_types = {"this": True, "is_string": True}
1167
1168    def __eq__(self, other):
1169        return (
1170            isinstance(other, Literal)
1171            and self.this == other.this
1172            and self.args["is_string"] == other.args["is_string"]
1173        )
1174
1175    def __hash__(self):
1176        return hash((self.key, self.this, self.args["is_string"]))
1177
1178    @classmethod
1179    def number(cls, number) -> Literal:
1180        return cls(this=str(number), is_string=False)
1181
1182    @classmethod
1183    def string(cls, string) -> Literal:
1184        return cls(this=str(string), is_string=True)
1185
1186    @property
1187    def output_name(self):
1188        return self.name
1189
1190
1191class Join(Expression):
1192    arg_types = {
1193        "this": True,
1194        "on": False,
1195        "side": False,
1196        "kind": False,
1197        "using": False,
1198        "natural": False,
1199    }
1200
1201    @property
1202    def kind(self):
1203        return self.text("kind").upper()
1204
1205    @property
1206    def side(self):
1207        return self.text("side").upper()
1208
1209    @property
1210    def alias_or_name(self):
1211        return self.this.alias_or_name
1212
1213    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1214        """
1215        Append to or set the ON expressions.
1216
1217        Example:
1218            >>> import sqlglot
1219            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1220            'JOIN x ON y = 1'
1221
1222        Args:
1223            *expressions (str | Expression): the SQL code strings to parse.
1224                If an `Expression` instance is passed, it will be used as-is.
1225                Multiple expressions are combined with an AND operator.
1226            append (bool): if `True`, AND the new expressions to any existing expression.
1227                Otherwise, this resets the expression.
1228            dialect (str): the dialect used to parse the input expressions.
1229            copy (bool): if `False`, modify this expression instance in-place.
1230            opts (kwargs): other options to use to parse the input expressions.
1231
1232        Returns:
1233            Join: the modified join expression.
1234        """
1235        join = _apply_conjunction_builder(
1236            *expressions,
1237            instance=self,
1238            arg="on",
1239            append=append,
1240            dialect=dialect,
1241            copy=copy,
1242            **opts,
1243        )
1244
1245        if join.kind == "CROSS":
1246            join.set("kind", None)
1247
1248        return join
1249
1250    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1251        """
1252        Append to or set the USING expressions.
1253
1254        Example:
1255            >>> import sqlglot
1256            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1257            'JOIN x USING (foo, bla)'
1258
1259        Args:
1260            *expressions (str | Expression): the SQL code strings to parse.
1261                If an `Expression` instance is passed, it will be used as-is.
1262            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1263                Otherwise, this resets the expression.
1264            dialect (str): the dialect used to parse the input expressions.
1265            copy (bool): if `False`, modify this expression instance in-place.
1266            opts (kwargs): other options to use to parse the input expressions.
1267
1268        Returns:
1269            Join: the modified join expression.
1270        """
1271        join = _apply_list_builder(
1272            *expressions,
1273            instance=self,
1274            arg="using",
1275            append=append,
1276            dialect=dialect,
1277            copy=copy,
1278            **opts,
1279        )
1280
1281        if join.kind == "CROSS":
1282            join.set("kind", None)
1283
1284        return join
1285
1286
1287class Lateral(UDTF):
1288    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
1289
1290
1291class MatchRecognize(Expression):
1292    arg_types = {
1293        "partition_by": False,
1294        "order": False,
1295        "measures": False,
1296        "rows": False,
1297        "after": False,
1298        "pattern": False,
1299        "define": False,
1300    }
1301
1302
1303# Clickhouse FROM FINAL modifier
1304# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier
1305class Final(Expression):
1306    pass
1307
1308
1309class Offset(Expression):
1310    arg_types = {"this": False, "expression": True}
1311
1312
1313class Order(Expression):
1314    arg_types = {"this": False, "expressions": True}
1315
1316
1317# hive specific sorts
1318# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy
1319class Cluster(Order):
1320    pass
1321
1322
1323class Distribute(Order):
1324    pass
1325
1326
1327class Sort(Order):
1328    pass
1329
1330
1331class Ordered(Expression):
1332    arg_types = {"this": True, "desc": True, "nulls_first": True}
1333
1334
1335class Property(Expression):
1336    arg_types = {"this": True, "value": True}
1337
1338
1339class AlgorithmProperty(Property):
1340    arg_types = {"this": True}
1341
1342
1343class DefinerProperty(Property):
1344    arg_types = {"this": True}
1345
1346
1347class SqlSecurityProperty(Property):
1348    arg_types = {"definer": True}
1349
1350
1351class TableFormatProperty(Property):
1352    arg_types = {"this": True}
1353
1354
1355class PartitionedByProperty(Property):
1356    arg_types = {"this": True}
1357
1358
1359class FileFormatProperty(Property):
1360    arg_types = {"this": True}
1361
1362
1363class DistKeyProperty(Property):
1364    arg_types = {"this": True}
1365
1366
1367class SortKeyProperty(Property):
1368    arg_types = {"this": True, "compound": False}
1369
1370
1371class DistStyleProperty(Property):
1372    arg_types = {"this": True}
1373
1374
1375class LikeProperty(Property):
1376    arg_types = {"this": True, "expressions": False}
1377
1378
1379class LocationProperty(Property):
1380    arg_types = {"this": True}
1381
1382
1383class EngineProperty(Property):
1384    arg_types = {"this": True}
1385
1386
1387class AutoIncrementProperty(Property):
1388    arg_types = {"this": True}
1389
1390
1391class CharacterSetProperty(Property):
1392    arg_types = {"this": True, "default": True}
1393
1394
1395class CollateProperty(Property):
1396    arg_types = {"this": True}
1397
1398
1399class SchemaCommentProperty(Property):
1400    arg_types = {"this": True}
1401
1402
1403class ReturnsProperty(Property):
1404    arg_types = {"this": True, "is_table": False, "table": False}
1405
1406
1407class LanguageProperty(Property):
1408    arg_types = {"this": True}
1409
1410
1411class ExecuteAsProperty(Property):
1412    arg_types = {"this": True}
1413
1414
1415class VolatilityProperty(Property):
1416    arg_types = {"this": True}
1417
1418
1419class RowFormatDelimitedProperty(Property):
1420    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
1421    arg_types = {
1422        "fields": False,
1423        "escaped": False,
1424        "collection_items": False,
1425        "map_keys": False,
1426        "lines": False,
1427        "null": False,
1428        "serde": False,
1429    }
1430
1431
1432class RowFormatSerdeProperty(Property):
1433    arg_types = {"this": True}
1434
1435
1436class SerdeProperties(Property):
1437    arg_types = {"expressions": True}
1438
1439
1440class FallbackProperty(Property):
1441    arg_types = {"no": True, "protection": False}
1442
1443
1444class WithJournalTableProperty(Property):
1445    arg_types = {"this": True}
1446
1447
1448class LogProperty(Property):
1449    arg_types = {"no": True}
1450
1451
1452class JournalProperty(Property):
1453    arg_types = {"no": True, "dual": False, "before": False}
1454
1455
1456class AfterJournalProperty(Property):
1457    arg_types = {"no": True, "dual": False, "local": False}
1458
1459
1460class ChecksumProperty(Property):
1461    arg_types = {"on": False, "default": False}
1462
1463
1464class FreespaceProperty(Property):
1465    arg_types = {"this": True, "percent": False}
1466
1467
1468class MergeBlockRatioProperty(Property):
1469    arg_types = {"this": False, "no": False, "default": False, "percent": False}
1470
1471
1472class DataBlocksizeProperty(Property):
1473    arg_types = {"size": False, "units": False, "min": False, "default": False}
1474
1475
1476class BlockCompressionProperty(Property):
1477    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
1478
1479
1480class IsolatedLoadingProperty(Property):
1481    arg_types = {
1482        "no": True,
1483        "concurrent": True,
1484        "for_all": True,
1485        "for_insert": True,
1486        "for_none": True,
1487    }
1488
1489
1490class LockingProperty(Property):
1491    arg_types = {
1492        "this": False,
1493        "kind": True,
1494        "for_or_in": True,
1495        "lock_type": True,
1496        "override": False,
1497    }
1498
1499
1500class Properties(Expression):
1501    arg_types = {"expressions": True}
1502
1503    NAME_TO_PROPERTY = {
1504        "ALGORITHM": AlgorithmProperty,
1505        "AUTO_INCREMENT": AutoIncrementProperty,
1506        "CHARACTER SET": CharacterSetProperty,
1507        "COLLATE": CollateProperty,
1508        "COMMENT": SchemaCommentProperty,
1509        "DEFINER": DefinerProperty,
1510        "DISTKEY": DistKeyProperty,
1511        "DISTSTYLE": DistStyleProperty,
1512        "ENGINE": EngineProperty,
1513        "EXECUTE AS": ExecuteAsProperty,
1514        "FORMAT": FileFormatProperty,
1515        "LANGUAGE": LanguageProperty,
1516        "LOCATION": LocationProperty,
1517        "PARTITIONED_BY": PartitionedByProperty,
1518        "RETURNS": ReturnsProperty,
1519        "SORTKEY": SortKeyProperty,
1520        "TABLE_FORMAT": TableFormatProperty,
1521    }
1522
1523    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
1524
1525    # CREATE property locations
1526    # Form: schema specified
1527    #   create [POST_CREATE]
1528    #     table a [POST_NAME]
1529    #     (b int) [POST_SCHEMA]
1530    #     with ([POST_WITH])
1531    #     index (b) [POST_INDEX]
1532    #
1533    # Form: alias selection
1534    #   create [POST_CREATE]
1535    #     table a [POST_NAME]
1536    #     as [POST_ALIAS] (select * from b)
1537    #     index (c) [POST_INDEX]
1538    class Location(AutoName):
1539        POST_CREATE = auto()
1540        POST_NAME = auto()
1541        POST_SCHEMA = auto()
1542        POST_WITH = auto()
1543        POST_ALIAS = auto()
1544        POST_INDEX = auto()
1545        UNSUPPORTED = auto()
1546
1547    @classmethod
1548    def from_dict(cls, properties_dict) -> Properties:
1549        expressions = []
1550        for key, value in properties_dict.items():
1551            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1552            if property_cls:
1553                expressions.append(property_cls(this=convert(value)))
1554            else:
1555                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1556
1557        return cls(expressions=expressions)
1558
1559
1560class Qualify(Expression):
1561    pass
1562
1563
1564# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql
1565class Return(Expression):
1566    pass
1567
1568
1569class Reference(Expression):
1570    arg_types = {"this": True, "expressions": False, "options": False}
1571
1572
1573class Tuple(Expression):
1574    arg_types = {"expressions": False}
1575
1576
1577class Subqueryable(Unionable):
1578    def subquery(self, alias=None, copy=True) -> Subquery:
1579        """
1580        Convert this expression to an aliased expression that can be used as a Subquery.
1581
1582        Example:
1583            >>> subquery = Select().select("x").from_("tbl").subquery()
1584            >>> Select().select("x").from_(subquery).sql()
1585            'SELECT x FROM (SELECT x FROM tbl)'
1586
1587        Args:
1588            alias (str | Identifier): an optional alias for the subquery
1589            copy (bool): if `False`, modify this expression instance in-place.
1590
1591        Returns:
1592            Alias: the subquery
1593        """
1594        instance = _maybe_copy(self, copy)
1595        return Subquery(
1596            this=instance,
1597            alias=TableAlias(this=to_identifier(alias)),
1598        )
1599
1600    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1601        raise NotImplementedError
1602
1603    @property
1604    def ctes(self):
1605        with_ = self.args.get("with")
1606        if not with_:
1607            return []
1608        return with_.expressions
1609
1610    @property
1611    def selects(self):
1612        raise NotImplementedError("Subqueryable objects must implement `selects`")
1613
1614    @property
1615    def named_selects(self):
1616        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
1617
1618    def with_(
1619        self,
1620        alias,
1621        as_,
1622        recursive=None,
1623        append=True,
1624        dialect=None,
1625        copy=True,
1626        **opts,
1627    ):
1628        """
1629        Append to or set the common table expressions.
1630
1631        Example:
1632            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1633            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1634
1635        Args:
1636            alias (str | Expression): the SQL code string to parse as the table name.
1637                If an `Expression` instance is passed, this is used as-is.
1638            as_ (str | Expression): the SQL code string to parse as the table expression.
1639                If an `Expression` instance is passed, it will be used as-is.
1640            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1641            append (bool): if `True`, add to any existing expressions.
1642                Otherwise, this resets the expressions.
1643            dialect (str): the dialect used to parse the input expression.
1644            copy (bool): if `False`, modify this expression instance in-place.
1645            opts (kwargs): other options to use to parse the input expressions.
1646
1647        Returns:
1648            Select: the modified expression.
1649        """
1650        alias_expression = maybe_parse(
1651            alias,
1652            dialect=dialect,
1653            into=TableAlias,
1654            **opts,
1655        )
1656        as_expression = maybe_parse(
1657            as_,
1658            dialect=dialect,
1659            **opts,
1660        )
1661        cte = CTE(
1662            this=as_expression,
1663            alias=alias_expression,
1664        )
1665        return _apply_child_list_builder(
1666            cte,
1667            instance=self,
1668            arg="with",
1669            append=append,
1670            copy=copy,
1671            into=With,
1672            properties={"recursive": recursive or False},
1673        )
1674
1675
1676QUERY_MODIFIERS = {
1677    "match": False,
1678    "laterals": False,
1679    "joins": False,
1680    "pivots": False,
1681    "where": False,
1682    "group": False,
1683    "having": False,
1684    "qualify": False,
1685    "windows": False,
1686    "distribute": False,
1687    "sort": False,
1688    "cluster": False,
1689    "order": False,
1690    "limit": False,
1691    "offset": False,
1692    "lock": False,
1693}
1694
1695
1696class Table(Expression):
1697    arg_types = {
1698        "this": True,
1699        "alias": False,
1700        "db": False,
1701        "catalog": False,
1702        "laterals": False,
1703        "joins": False,
1704        "pivots": False,
1705        "hints": False,
1706        "system_time": False,
1707    }
1708
1709    @property
1710    def db(self) -> str:
1711        return self.text("db")
1712
1713    @property
1714    def catalog(self) -> str:
1715        return self.text("catalog")
1716
1717
1718# See the TSQL "Querying data in a system-versioned temporal table" page
1719class SystemTime(Expression):
1720    arg_types = {
1721        "this": False,
1722        "expression": False,
1723        "kind": True,
1724    }
1725
1726
1727class Union(Subqueryable):
1728    arg_types = {
1729        "with": False,
1730        "this": True,
1731        "expression": True,
1732        "distinct": False,
1733        **QUERY_MODIFIERS,
1734    }
1735
1736    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1737        """
1738        Set the LIMIT expression.
1739
1740        Example:
1741            >>> select("1").union(select("1")).limit(1).sql()
1742            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1743
1744        Args:
1745            expression (str | int | Expression): the SQL code string to parse.
1746                This can also be an integer.
1747                If a `Limit` instance is passed, this is used as-is.
1748                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1749            dialect (str): the dialect used to parse the input expression.
1750            copy (bool): if `False`, modify this expression instance in-place.
1751            opts (kwargs): other options to use to parse the input expressions.
1752
1753        Returns:
1754            Select: The limited subqueryable.
1755        """
1756        return (
1757            select("*")
1758            .from_(self.subquery(alias="_l_0", copy=copy))
1759            .limit(expression, dialect=dialect, copy=False, **opts)
1760        )
1761
1762    def select(
1763        self,
1764        *expressions: str | Expression,
1765        append: bool = True,
1766        dialect: DialectType = None,
1767        copy: bool = True,
1768        **opts,
1769    ) -> Union:
1770        """Append to or set the SELECT of the union recursively.
1771
1772        Example:
1773            >>> from sqlglot import parse_one
1774            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1775            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1776
1777        Args:
1778            *expressions: the SQL code strings to parse.
1779                If an `Expression` instance is passed, it will be used as-is.
1780            append: if `True`, add to any existing expressions.
1781                Otherwise, this resets the expressions.
1782            dialect: the dialect used to parse the input expressions.
1783            copy: if `False`, modify this expression instance in-place.
1784            opts: other options to use to parse the input expressions.
1785
1786        Returns:
1787            Union: the modified expression.
1788        """
1789        this = self.copy() if copy else self
1790        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1791        this.expression.unnest().select(
1792            *expressions, append=append, dialect=dialect, copy=False, **opts
1793        )
1794        return this
1795
1796    @property
1797    def named_selects(self):
1798        return self.this.unnest().named_selects
1799
1800    @property
1801    def selects(self):
1802        return self.this.unnest().selects
1803
1804    @property
1805    def left(self):
1806        return self.this
1807
1808    @property
1809    def right(self):
1810        return self.expression
1811
1812
1813class Except(Union):
1814    pass
1815
1816
1817class Intersect(Union):
1818    pass
1819
1820
1821class Unnest(UDTF):
1822    arg_types = {
1823        "expressions": True,
1824        "ordinality": False,
1825        "alias": False,
1826        "offset": False,
1827    }
1828
1829
1830class Update(Expression):
1831    arg_types = {
1832        "with": False,
1833        "this": False,
1834        "expressions": True,
1835        "from": False,
1836        "where": False,
1837    }
1838
1839
1840class Values(UDTF):
1841    arg_types = {
1842        "expressions": True,
1843        "ordinality": False,
1844        "alias": False,
1845    }
1846
1847
1848class Var(Expression):
1849    pass
1850
1851
1852class Schema(Expression):
1853    arg_types = {"this": False, "expressions": False}
1854
1855
1856# Used to represent the FOR UPDATE and FOR SHARE locking read types.
1857# https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html
1858class Lock(Expression):
1859    arg_types = {"update": True}
1860
1861
1862class Select(Subqueryable):
1863    arg_types = {
1864        "with": False,
1865        "expressions": False,
1866        "hint": False,
1867        "distinct": False,
1868        "into": False,
1869        "from": False,
1870        **QUERY_MODIFIERS,
1871    }
1872
1873    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1874        """
1875        Set the FROM expression.
1876
1877        Example:
1878            >>> Select().from_("tbl").select("x").sql()
1879            'SELECT x FROM tbl'
1880
1881        Args:
1882            *expressions (str | Expression): the SQL code strings to parse.
1883                If a `From` instance is passed, this is used as-is.
1884                If another `Expression` instance is passed, it will be wrapped in a `From`.
1885            append (bool): if `True`, add to any existing expressions.
1886                Otherwise, this flattens all the `From` expression into a single expression.
1887            dialect (str): the dialect used to parse the input expression.
1888            copy (bool): if `False`, modify this expression instance in-place.
1889            opts (kwargs): other options to use to parse the input expressions.
1890
1891        Returns:
1892            Select: the modified expression.
1893        """
1894        return _apply_child_list_builder(
1895            *expressions,
1896            instance=self,
1897            arg="from",
1898            append=append,
1899            copy=copy,
1900            prefix="FROM",
1901            into=From,
1902            dialect=dialect,
1903            **opts,
1904        )
1905
1906    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1907        """
1908        Set the GROUP BY expression.
1909
1910        Example:
1911            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1912            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1913
1914        Args:
1915            *expressions (str | Expression): the SQL code strings to parse.
1916                If a `Group` instance is passed, this is used as-is.
1917                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1918                If nothing is passed in then a group by is not applied to the expression
1919            append (bool): if `True`, add to any existing expressions.
1920                Otherwise, this flattens all the `Group` expression into a single expression.
1921            dialect (str): the dialect used to parse the input expression.
1922            copy (bool): if `False`, modify this expression instance in-place.
1923            opts (kwargs): other options to use to parse the input expressions.
1924
1925        Returns:
1926            Select: the modified expression.
1927        """
1928        if not expressions:
1929            return self if not copy else self.copy()
1930        return _apply_child_list_builder(
1931            *expressions,
1932            instance=self,
1933            arg="group",
1934            append=append,
1935            copy=copy,
1936            prefix="GROUP BY",
1937            into=Group,
1938            dialect=dialect,
1939            **opts,
1940        )
1941
1942    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1943        """
1944        Set the ORDER BY expression.
1945
1946        Example:
1947            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
1948            'SELECT x FROM tbl ORDER BY x DESC'
1949
1950        Args:
1951            *expressions (str | Expression): the SQL code strings to parse.
1952                If a `Group` instance is passed, this is used as-is.
1953                If another `Expression` instance is passed, it will be wrapped in a `Order`.
1954            append (bool): if `True`, add to any existing expressions.
1955                Otherwise, this flattens all the `Order` expression into a single expression.
1956            dialect (str): the dialect used to parse the input expression.
1957            copy (bool): if `False`, modify this expression instance in-place.
1958            opts (kwargs): other options to use to parse the input expressions.
1959
1960        Returns:
1961            Select: the modified expression.
1962        """
1963        return _apply_child_list_builder(
1964            *expressions,
1965            instance=self,
1966            arg="order",
1967            append=append,
1968            copy=copy,
1969            prefix="ORDER BY",
1970            into=Order,
1971            dialect=dialect,
1972            **opts,
1973        )
1974
1975    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1976        """
1977        Set the SORT BY expression.
1978
1979        Example:
1980            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
1981            'SELECT x FROM tbl SORT BY x DESC'
1982
1983        Args:
1984            *expressions (str | Expression): the SQL code strings to parse.
1985                If a `Group` instance is passed, this is used as-is.
1986                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
1987            append (bool): if `True`, add to any existing expressions.
1988                Otherwise, this flattens all the `Order` expression into a single expression.
1989            dialect (str): the dialect used to parse the input expression.
1990            copy (bool): if `False`, modify this expression instance in-place.
1991            opts (kwargs): other options to use to parse the input expressions.
1992
1993        Returns:
1994            Select: the modified expression.
1995        """
1996        return _apply_child_list_builder(
1997            *expressions,
1998            instance=self,
1999            arg="sort",
2000            append=append,
2001            copy=copy,
2002            prefix="SORT BY",
2003            into=Sort,
2004            dialect=dialect,
2005            **opts,
2006        )
2007
2008    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2009        """
2010        Set the CLUSTER BY expression.
2011
2012        Example:
2013            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2014            'SELECT x FROM tbl CLUSTER BY x DESC'
2015
2016        Args:
2017            *expressions (str | Expression): the SQL code strings to parse.
2018                If a `Group` instance is passed, this is used as-is.
2019                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2020            append (bool): if `True`, add to any existing expressions.
2021                Otherwise, this flattens all the `Order` expression into a single expression.
2022            dialect (str): the dialect used to parse the input expression.
2023            copy (bool): if `False`, modify this expression instance in-place.
2024            opts (kwargs): other options to use to parse the input expressions.
2025
2026        Returns:
2027            Select: the modified expression.
2028        """
2029        return _apply_child_list_builder(
2030            *expressions,
2031            instance=self,
2032            arg="cluster",
2033            append=append,
2034            copy=copy,
2035            prefix="CLUSTER BY",
2036            into=Cluster,
2037            dialect=dialect,
2038            **opts,
2039        )
2040
2041    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2042        """
2043        Set the LIMIT expression.
2044
2045        Example:
2046            >>> Select().from_("tbl").select("x").limit(10).sql()
2047            'SELECT x FROM tbl LIMIT 10'
2048
2049        Args:
2050            expression (str | int | Expression): the SQL code string to parse.
2051                This can also be an integer.
2052                If a `Limit` instance is passed, this is used as-is.
2053                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2054            dialect (str): the dialect used to parse the input expression.
2055            copy (bool): if `False`, modify this expression instance in-place.
2056            opts (kwargs): other options to use to parse the input expressions.
2057
2058        Returns:
2059            Select: the modified expression.
2060        """
2061        return _apply_builder(
2062            expression=expression,
2063            instance=self,
2064            arg="limit",
2065            into=Limit,
2066            prefix="LIMIT",
2067            dialect=dialect,
2068            copy=copy,
2069            **opts,
2070        )
2071
2072    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2073        """
2074        Set the OFFSET expression.
2075
2076        Example:
2077            >>> Select().from_("tbl").select("x").offset(10).sql()
2078            'SELECT x FROM tbl OFFSET 10'
2079
2080        Args:
2081            expression (str | int | Expression): the SQL code string to parse.
2082                This can also be an integer.
2083                If a `Offset` instance is passed, this is used as-is.
2084                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2085            dialect (str): the dialect used to parse the input expression.
2086            copy (bool): if `False`, modify this expression instance in-place.
2087            opts (kwargs): other options to use to parse the input expressions.
2088
2089        Returns:
2090            Select: the modified expression.
2091        """
2092        return _apply_builder(
2093            expression=expression,
2094            instance=self,
2095            arg="offset",
2096            into=Offset,
2097            prefix="OFFSET",
2098            dialect=dialect,
2099            copy=copy,
2100            **opts,
2101        )
2102
2103    def select(
2104        self,
2105        *expressions: str | Expression,
2106        append: bool = True,
2107        dialect: DialectType = None,
2108        copy: bool = True,
2109        **opts,
2110    ) -> Select:
2111        """
2112        Append to or set the SELECT expressions.
2113
2114        Example:
2115            >>> Select().select("x", "y").sql()
2116            'SELECT x, y'
2117
2118        Args:
2119            *expressions: the SQL code strings to parse.
2120                If an `Expression` instance is passed, it will be used as-is.
2121            append: if `True`, add to any existing expressions.
2122                Otherwise, this resets the expressions.
2123            dialect: the dialect used to parse the input expressions.
2124            copy: if `False`, modify this expression instance in-place.
2125            opts: other options to use to parse the input expressions.
2126
2127        Returns:
2128            Select: the modified expression.
2129        """
2130        return _apply_list_builder(
2131            *expressions,
2132            instance=self,
2133            arg="expressions",
2134            append=append,
2135            dialect=dialect,
2136            copy=copy,
2137            **opts,
2138        )
2139
2140    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2141        """
2142        Append to or set the LATERAL expressions.
2143
2144        Example:
2145            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2146            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2147
2148        Args:
2149            *expressions (str | Expression): the SQL code strings to parse.
2150                If an `Expression` instance is passed, it will be used as-is.
2151            append (bool): if `True`, add to any existing expressions.
2152                Otherwise, this resets the expressions.
2153            dialect (str): the dialect used to parse the input expressions.
2154            copy (bool): if `False`, modify this expression instance in-place.
2155            opts (kwargs): other options to use to parse the input expressions.
2156
2157        Returns:
2158            Select: the modified expression.
2159        """
2160        return _apply_list_builder(
2161            *expressions,
2162            instance=self,
2163            arg="laterals",
2164            append=append,
2165            into=Lateral,
2166            prefix="LATERAL VIEW",
2167            dialect=dialect,
2168            copy=copy,
2169            **opts,
2170        )
2171
2172    def join(
2173        self,
2174        expression,
2175        on=None,
2176        using=None,
2177        append=True,
2178        join_type=None,
2179        join_alias=None,
2180        dialect=None,
2181        copy=True,
2182        **opts,
2183    ) -> Select:
2184        """
2185        Append to or set the JOIN expressions.
2186
2187        Example:
2188            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2189            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2190
2191            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2192            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2193
2194            Use `join_type` to change the type of join:
2195
2196            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2197            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2198
2199        Args:
2200            expression (str | Expression): the SQL code string to parse.
2201                If an `Expression` instance is passed, it will be used as-is.
2202            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2203                If an `Expression` instance is passed, it will be used as-is.
2204            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2205                If an `Expression` instance is passed, it will be used as-is.
2206            append (bool): if `True`, add to any existing expressions.
2207                Otherwise, this resets the expressions.
2208            join_type (str): If set, alter the parsed join type
2209            dialect (str): the dialect used to parse the input expressions.
2210            copy (bool): if `False`, modify this expression instance in-place.
2211            opts (kwargs): other options to use to parse the input expressions.
2212
2213        Returns:
2214            Select: the modified expression.
2215        """
2216        parse_args = {"dialect": dialect, **opts}
2217
2218        try:
2219            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2220        except ParseError:
2221            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2222
2223        join = expression if isinstance(expression, Join) else Join(this=expression)
2224
2225        if isinstance(join.this, Select):
2226            join.this.replace(join.this.subquery())
2227
2228        if join_type:
2229            natural: t.Optional[Token]
2230            side: t.Optional[Token]
2231            kind: t.Optional[Token]
2232
2233            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2234
2235            if natural:
2236                join.set("natural", True)
2237            if side:
2238                join.set("side", side.text)
2239            if kind:
2240                join.set("kind", kind.text)
2241
2242        if on:
2243            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2244            join.set("on", on)
2245
2246        if using:
2247            join = _apply_list_builder(
2248                *ensure_collection(using),
2249                instance=join,
2250                arg="using",
2251                append=append,
2252                copy=copy,
2253                **opts,
2254            )
2255
2256        if join_alias:
2257            join.set("this", alias_(join.this, join_alias, table=True))
2258        return _apply_list_builder(
2259            join,
2260            instance=self,
2261            arg="joins",
2262            append=append,
2263            copy=copy,
2264            **opts,
2265        )
2266
2267    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2268        """
2269        Append to or set the WHERE expressions.
2270
2271        Example:
2272            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2273            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2274
2275        Args:
2276            *expressions (str | Expression): the SQL code strings to parse.
2277                If an `Expression` instance is passed, it will be used as-is.
2278                Multiple expressions are combined with an AND operator.
2279            append (bool): if `True`, AND the new expressions to any existing expression.
2280                Otherwise, this resets the expression.
2281            dialect (str): the dialect used to parse the input expressions.
2282            copy (bool): if `False`, modify this expression instance in-place.
2283            opts (kwargs): other options to use to parse the input expressions.
2284
2285        Returns:
2286            Select: the modified expression.
2287        """
2288        return _apply_conjunction_builder(
2289            *expressions,
2290            instance=self,
2291            arg="where",
2292            append=append,
2293            into=Where,
2294            dialect=dialect,
2295            copy=copy,
2296            **opts,
2297        )
2298
2299    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2300        """
2301        Append to or set the HAVING expressions.
2302
2303        Example:
2304            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2305            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2306
2307        Args:
2308            *expressions (str | Expression): the SQL code strings to parse.
2309                If an `Expression` instance is passed, it will be used as-is.
2310                Multiple expressions are combined with an AND operator.
2311            append (bool): if `True`, AND the new expressions to any existing expression.
2312                Otherwise, this resets the expression.
2313            dialect (str): the dialect used to parse the input expressions.
2314            copy (bool): if `False`, modify this expression instance in-place.
2315            opts (kwargs): other options to use to parse the input expressions.
2316
2317        Returns:
2318            Select: the modified expression.
2319        """
2320        return _apply_conjunction_builder(
2321            *expressions,
2322            instance=self,
2323            arg="having",
2324            append=append,
2325            into=Having,
2326            dialect=dialect,
2327            copy=copy,
2328            **opts,
2329        )
2330
2331    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2332        return _apply_list_builder(
2333            *expressions,
2334            instance=self,
2335            arg="windows",
2336            append=append,
2337            into=Window,
2338            dialect=dialect,
2339            copy=copy,
2340            **opts,
2341        )
2342
2343    def distinct(self, distinct=True, copy=True) -> Select:
2344        """
2345        Set the OFFSET expression.
2346
2347        Example:
2348            >>> Select().from_("tbl").select("x").distinct().sql()
2349            'SELECT DISTINCT x FROM tbl'
2350
2351        Args:
2352            distinct (bool): whether the Select should be distinct
2353            copy (bool): if `False`, modify this expression instance in-place.
2354
2355        Returns:
2356            Select: the modified expression.
2357        """
2358        instance = _maybe_copy(self, copy)
2359        instance.set("distinct", Distinct() if distinct else None)
2360        return instance
2361
2362    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2363        """
2364        Convert this expression to a CREATE TABLE AS statement.
2365
2366        Example:
2367            >>> Select().select("*").from_("tbl").ctas("x").sql()
2368            'CREATE TABLE x AS SELECT * FROM tbl'
2369
2370        Args:
2371            table (str | Expression): the SQL code string to parse as the table name.
2372                If another `Expression` instance is passed, it will be used as-is.
2373            properties (dict): an optional mapping of table properties
2374            dialect (str): the dialect used to parse the input table.
2375            copy (bool): if `False`, modify this expression instance in-place.
2376            opts (kwargs): other options to use to parse the input table.
2377
2378        Returns:
2379            Create: the CREATE TABLE AS expression
2380        """
2381        instance = _maybe_copy(self, copy)
2382        table_expression = maybe_parse(
2383            table,
2384            into=Table,
2385            dialect=dialect,
2386            **opts,
2387        )
2388        properties_expression = None
2389        if properties:
2390            properties_expression = Properties.from_dict(properties)
2391
2392        return Create(
2393            this=table_expression,
2394            kind="table",
2395            expression=instance,
2396            properties=properties_expression,
2397        )
2398
2399    def lock(self, update: bool = True, copy: bool = True) -> Select:
2400        """
2401        Set the locking read mode for this expression.
2402
2403        Examples:
2404            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2405            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2406
2407            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2408            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2409
2410        Args:
2411            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2412            copy: if `False`, modify this expression instance in-place.
2413
2414        Returns:
2415            The modified expression.
2416        """
2417
2418        inst = _maybe_copy(self, copy)
2419        inst.set("lock", Lock(update=update))
2420
2421        return inst
2422
2423    @property
2424    def named_selects(self) -> t.List[str]:
2425        return [e.output_name for e in self.expressions if e.alias_or_name]
2426
2427    @property
2428    def selects(self) -> t.List[Expression]:
2429        return self.expressions
2430
2431
2432class Subquery(DerivedTable, Unionable):
2433    arg_types = {
2434        "this": True,
2435        "alias": False,
2436        "with": False,
2437        **QUERY_MODIFIERS,
2438    }
2439
2440    def unnest(self):
2441        """
2442        Returns the first non subquery.
2443        """
2444        expression = self
2445        while isinstance(expression, Subquery):
2446            expression = expression.this
2447        return expression
2448
2449    @property
2450    def output_name(self):
2451        return self.alias
2452
2453
2454class TableSample(Expression):
2455    arg_types = {
2456        "this": False,
2457        "method": False,
2458        "bucket_numerator": False,
2459        "bucket_denominator": False,
2460        "bucket_field": False,
2461        "percent": False,
2462        "rows": False,
2463        "size": False,
2464        "seed": False,
2465    }
2466
2467
2468class Tag(Expression):
2469    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
2470
2471    arg_types = {
2472        "this": False,
2473        "prefix": False,
2474        "postfix": False,
2475    }
2476
2477
2478class Pivot(Expression):
2479    arg_types = {
2480        "this": False,
2481        "expressions": True,
2482        "field": True,
2483        "unpivot": True,
2484    }
2485
2486
2487class Window(Expression):
2488    arg_types = {
2489        "this": True,
2490        "partition_by": False,
2491        "order": False,
2492        "spec": False,
2493        "alias": False,
2494    }
2495
2496
2497class WindowSpec(Expression):
2498    arg_types = {
2499        "kind": False,
2500        "start": False,
2501        "start_side": False,
2502        "end": False,
2503        "end_side": False,
2504    }
2505
2506
2507class Where(Expression):
2508    pass
2509
2510
2511class Star(Expression):
2512    arg_types = {"except": False, "replace": False}
2513
2514    @property
2515    def name(self) -> str:
2516        return "*"
2517
2518    @property
2519    def output_name(self):
2520        return self.name
2521
2522
2523class Parameter(Expression):
2524    arg_types = {"this": True, "wrapped": False}
2525
2526
2527class SessionParameter(Expression):
2528    arg_types = {"this": True, "kind": False}
2529
2530
2531class Placeholder(Expression):
2532    arg_types = {"this": False}
2533
2534
2535class Null(Condition):
2536    arg_types: t.Dict[str, t.Any] = {}
2537
2538    @property
2539    def name(self) -> str:
2540        return "NULL"
2541
2542
2543class Boolean(Condition):
2544    pass
2545
2546
2547class DataType(Expression):
2548    arg_types = {
2549        "this": True,
2550        "expressions": False,
2551        "nested": False,
2552        "values": False,
2553        "prefix": False,
2554    }
2555
2556    class Type(AutoName):
2557        CHAR = auto()
2558        NCHAR = auto()
2559        VARCHAR = auto()
2560        NVARCHAR = auto()
2561        TEXT = auto()
2562        MEDIUMTEXT = auto()
2563        LONGTEXT = auto()
2564        MEDIUMBLOB = auto()
2565        LONGBLOB = auto()
2566        BINARY = auto()
2567        VARBINARY = auto()
2568        INT = auto()
2569        TINYINT = auto()
2570        SMALLINT = auto()
2571        BIGINT = auto()
2572        FLOAT = auto()
2573        DOUBLE = auto()
2574        DECIMAL = auto()
2575        BOOLEAN = auto()
2576        JSON = auto()
2577        JSONB = auto()
2578        INTERVAL = auto()
2579        TIME = auto()
2580        TIMESTAMP = auto()
2581        TIMESTAMPTZ = auto()
2582        TIMESTAMPLTZ = auto()
2583        DATE = auto()
2584        DATETIME = auto()
2585        ARRAY = auto()
2586        MAP = auto()
2587        UUID = auto()
2588        GEOGRAPHY = auto()
2589        GEOMETRY = auto()
2590        STRUCT = auto()
2591        NULLABLE = auto()
2592        HLLSKETCH = auto()
2593        HSTORE = auto()
2594        SUPER = auto()
2595        SERIAL = auto()
2596        SMALLSERIAL = auto()
2597        BIGSERIAL = auto()
2598        XML = auto()
2599        UNIQUEIDENTIFIER = auto()
2600        MONEY = auto()
2601        SMALLMONEY = auto()
2602        ROWVERSION = auto()
2603        IMAGE = auto()
2604        VARIANT = auto()
2605        OBJECT = auto()
2606        NULL = auto()
2607        UNKNOWN = auto()  # Sentinel value, useful for type annotation
2608
2609    TEXT_TYPES = {
2610        Type.CHAR,
2611        Type.NCHAR,
2612        Type.VARCHAR,
2613        Type.NVARCHAR,
2614        Type.TEXT,
2615    }
2616
2617    INTEGER_TYPES = {
2618        Type.INT,
2619        Type.TINYINT,
2620        Type.SMALLINT,
2621        Type.BIGINT,
2622    }
2623
2624    FLOAT_TYPES = {
2625        Type.FLOAT,
2626        Type.DOUBLE,
2627    }
2628
2629    NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES}
2630
2631    TEMPORAL_TYPES = {
2632        Type.TIMESTAMP,
2633        Type.TIMESTAMPTZ,
2634        Type.TIMESTAMPLTZ,
2635        Type.DATE,
2636        Type.DATETIME,
2637    }
2638
2639    @classmethod
2640    def build(
2641        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2642    ) -> DataType:
2643        from sqlglot import parse_one
2644
2645        if isinstance(dtype, str):
2646            if dtype.upper() in cls.Type.__members__:
2647                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2648            else:
2649                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2650            if data_type_exp is None:
2651                raise ValueError(f"Unparsable data type value: {dtype}")
2652        elif isinstance(dtype, DataType.Type):
2653            data_type_exp = DataType(this=dtype)
2654        elif isinstance(dtype, DataType):
2655            return dtype
2656        else:
2657            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2658        return DataType(**{**data_type_exp.args, **kwargs})
2659
2660    def is_type(self, dtype: DataType.Type) -> bool:
2661        return self.this == dtype
2662
2663
2664# https://www.postgresql.org/docs/15/datatype-pseudo.html
2665class PseudoType(Expression):
2666    pass
2667
2668
2669class StructKwarg(Expression):
2670    arg_types = {"this": True, "expression": True}
2671
2672
2673# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...)
2674class SubqueryPredicate(Predicate):
2675    pass
2676
2677
2678class All(SubqueryPredicate):
2679    pass
2680
2681
2682class Any(SubqueryPredicate):
2683    pass
2684
2685
2686class Exists(SubqueryPredicate):
2687    pass
2688
2689
2690# Commands to interact with the databases or engines. For most of the command
2691# expressions we parse whatever comes after the command's name as a string.
2692class Command(Expression):
2693    arg_types = {"this": True, "expression": False}
2694
2695
2696class Transaction(Expression):
2697    arg_types = {"this": False, "modes": False}
2698
2699
2700class Commit(Expression):
2701    arg_types = {"chain": False}
2702
2703
2704class Rollback(Expression):
2705    arg_types = {"savepoint": False}
2706
2707
2708class AlterTable(Expression):
2709    arg_types = {"this": True, "actions": True, "exists": False}
2710
2711
2712class AddConstraint(Expression):
2713    arg_types = {"this": False, "expression": False, "enforced": False}
2714
2715
2716class DropPartition(Expression):
2717    arg_types = {"expressions": True, "exists": False}
2718
2719
2720# Binary expressions like (ADD a b)
2721class Binary(Expression):
2722    arg_types = {"this": True, "expression": True}
2723
2724    @property
2725    def left(self):
2726        return self.this
2727
2728    @property
2729    def right(self):
2730        return self.expression
2731
2732
2733class Add(Binary):
2734    pass
2735
2736
2737class Connector(Binary, Condition):
2738    pass
2739
2740
2741class And(Connector):
2742    pass
2743
2744
2745class Or(Connector):
2746    pass
2747
2748
2749class BitwiseAnd(Binary):
2750    pass
2751
2752
2753class BitwiseLeftShift(Binary):
2754    pass
2755
2756
2757class BitwiseOr(Binary):
2758    pass
2759
2760
2761class BitwiseRightShift(Binary):
2762    pass
2763
2764
2765class BitwiseXor(Binary):
2766    pass
2767
2768
2769class Div(Binary):
2770    pass
2771
2772
2773class Dot(Binary):
2774    @property
2775    def name(self) -> str:
2776        return self.expression.name
2777
2778
2779class DPipe(Binary):
2780    pass
2781
2782
2783class EQ(Binary, Predicate):
2784    pass
2785
2786
2787class NullSafeEQ(Binary, Predicate):
2788    pass
2789
2790
2791class NullSafeNEQ(Binary, Predicate):
2792    pass
2793
2794
2795class Distance(Binary):
2796    pass
2797
2798
2799class Escape(Binary):
2800    pass
2801
2802
2803class Glob(Binary, Predicate):
2804    pass
2805
2806
2807class GT(Binary, Predicate):
2808    pass
2809
2810
2811class GTE(Binary, Predicate):
2812    pass
2813
2814
2815class ILike(Binary, Predicate):
2816    pass
2817
2818
2819class ILikeAny(Binary, Predicate):
2820    pass
2821
2822
2823class IntDiv(Binary):
2824    pass
2825
2826
2827class Is(Binary, Predicate):
2828    pass
2829
2830
2831class Kwarg(Binary):
2832    """Kwarg in special functions like func(kwarg => y)."""
2833
2834
2835class Like(Binary, Predicate):
2836    pass
2837
2838
2839class LikeAny(Binary, Predicate):
2840    pass
2841
2842
2843class LT(Binary, Predicate):
2844    pass
2845
2846
2847class LTE(Binary, Predicate):
2848    pass
2849
2850
2851class Mod(Binary):
2852    pass
2853
2854
2855class Mul(Binary):
2856    pass
2857
2858
2859class NEQ(Binary, Predicate):
2860    pass
2861
2862
2863class SimilarTo(Binary, Predicate):
2864    pass
2865
2866
2867class Slice(Binary):
2868    arg_types = {"this": False, "expression": False}
2869
2870
2871class Sub(Binary):
2872    pass
2873
2874
2875# Unary Expressions
2876# (NOT a)
2877class Unary(Expression):
2878    pass
2879
2880
2881class BitwiseNot(Unary):
2882    pass
2883
2884
2885class Not(Unary, Condition):
2886    pass
2887
2888
2889class Paren(Unary, Condition):
2890    arg_types = {"this": True, "with": False}
2891
2892
2893class Neg(Unary):
2894    pass
2895
2896
2897# Special Functions
2898class Alias(Expression):
2899    arg_types = {"this": True, "alias": False}
2900
2901    @property
2902    def output_name(self):
2903        return self.alias
2904
2905
2906class Aliases(Expression):
2907    arg_types = {"this": True, "expressions": True}
2908
2909    @property
2910    def aliases(self):
2911        return self.expressions
2912
2913
2914class AtTimeZone(Expression):
2915    arg_types = {"this": True, "zone": True}
2916
2917
2918class Between(Predicate):
2919    arg_types = {"this": True, "low": True, "high": True}
2920
2921
2922class Bracket(Condition):
2923    arg_types = {"this": True, "expressions": True}
2924
2925
2926class Distinct(Expression):
2927    arg_types = {"expressions": False, "on": False}
2928
2929
2930class In(Predicate):
2931    arg_types = {
2932        "this": True,
2933        "expressions": False,
2934        "query": False,
2935        "unnest": False,
2936        "field": False,
2937        "is_global": False,
2938    }
2939
2940
2941class TimeUnit(Expression):
2942    """Automatically converts unit arg into a var."""
2943
2944    arg_types = {"unit": False}
2945
2946    def __init__(self, **args):
2947        unit = args.get("unit")
2948        if isinstance(unit, Column):
2949            args["unit"] = Var(this=unit.name)
2950        elif isinstance(unit, Week):
2951            unit.set("this", Var(this=unit.this.name))
2952        super().__init__(**args)
2953
2954
2955class Interval(TimeUnit):
2956    arg_types = {"this": False, "unit": False}
2957
2958
2959class IgnoreNulls(Expression):
2960    pass
2961
2962
2963class RespectNulls(Expression):
2964    pass
2965
2966
2967# Functions
2968class Func(Condition):
2969    """
2970    The base class for all function expressions.
2971
2972    Attributes:
2973        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
2974            treated as a variable length argument and the argument's value will be stored as a list.
2975        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
2976            for this function expression. These values are used to map this node to a name during parsing
2977            as well as to provide the function's name during SQL string generation. By default the SQL
2978            name is set to the expression's class name transformed to snake case.
2979    """
2980
2981    is_var_len_args = False
2982
2983    @classmethod
2984    def from_arg_list(cls, args):
2985        if cls.is_var_len_args:
2986            all_arg_keys = list(cls.arg_types)
2987            # If this function supports variable length argument treat the last argument as such.
2988            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
2989            num_non_var = len(non_var_len_arg_keys)
2990
2991            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
2992            args_dict[all_arg_keys[-1]] = args[num_non_var:]
2993        else:
2994            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
2995
2996        return cls(**args_dict)
2997
2998    @classmethod
2999    def sql_names(cls):
3000        if cls is Func:
3001            raise NotImplementedError(
3002                "SQL name is only supported by concrete function implementations"
3003            )
3004        if "_sql_names" not in cls.__dict__:
3005            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3006        return cls._sql_names
3007
3008    @classmethod
3009    def sql_name(cls):
3010        return cls.sql_names()[0]
3011
3012    @classmethod
3013    def default_parser_mappings(cls):
3014        return {name: cls.from_arg_list for name in cls.sql_names()}
3015
3016
3017class AggFunc(Func):
3018    pass
3019
3020
3021class Abs(Func):
3022    pass
3023
3024
3025class Anonymous(Func):
3026    arg_types = {"this": True, "expressions": False}
3027    is_var_len_args = True
3028
3029
3030class ApproxDistinct(AggFunc):
3031    arg_types = {"this": True, "accuracy": False}
3032
3033
3034class Array(Func):
3035    arg_types = {"expressions": False}
3036    is_var_len_args = True
3037
3038
3039class GenerateSeries(Func):
3040    arg_types = {"start": True, "end": True, "step": False}
3041
3042
3043class ArrayAgg(AggFunc):
3044    pass
3045
3046
3047class ArrayAll(Func):
3048    arg_types = {"this": True, "expression": True}
3049
3050
3051class ArrayAny(Func):
3052    arg_types = {"this": True, "expression": True}
3053
3054
3055class ArrayConcat(Func):
3056    arg_types = {"this": True, "expressions": False}
3057    is_var_len_args = True
3058
3059
3060class ArrayContains(Func):
3061    arg_types = {"this": True, "expression": True}
3062
3063
3064class ArrayFilter(Func):
3065    arg_types = {"this": True, "expression": True}
3066    _sql_names = ["FILTER", "ARRAY_FILTER"]
3067
3068
3069class ArraySize(Func):
3070    arg_types = {"this": True, "expression": False}
3071
3072
3073class ArraySort(Func):
3074    arg_types = {"this": True, "expression": False}
3075
3076
3077class ArraySum(Func):
3078    pass
3079
3080
3081class ArrayUnionAgg(AggFunc):
3082    pass
3083
3084
3085class Avg(AggFunc):
3086    pass
3087
3088
3089class AnyValue(AggFunc):
3090    pass
3091
3092
3093class Case(Func):
3094    arg_types = {"this": False, "ifs": True, "default": False}
3095
3096
3097class Cast(Func):
3098    arg_types = {"this": True, "to": True}
3099
3100    @property
3101    def name(self) -> str:
3102        return self.this.name
3103
3104    @property
3105    def to(self):
3106        return self.args["to"]
3107
3108    @property
3109    def output_name(self):
3110        return self.name
3111
3112    def is_type(self, dtype: DataType.Type) -> bool:
3113        return self.to.is_type(dtype)
3114
3115
3116class Collate(Binary):
3117    pass
3118
3119
3120class TryCast(Cast):
3121    pass
3122
3123
3124class Ceil(Func):
3125    arg_types = {"this": True, "decimals": False}
3126    _sql_names = ["CEIL", "CEILING"]
3127
3128
3129class Coalesce(Func):
3130    arg_types = {"this": True, "expressions": False}
3131    is_var_len_args = True
3132
3133
3134class Concat(Func):
3135    arg_types = {"expressions": True}
3136    is_var_len_args = True
3137
3138
3139class ConcatWs(Concat):
3140    _sql_names = ["CONCAT_WS"]
3141
3142
3143class Count(AggFunc):
3144    arg_types = {"this": False}
3145
3146
3147class CurrentDate(Func):
3148    arg_types = {"this": False}
3149
3150
3151class CurrentDatetime(Func):
3152    arg_types = {"this": False}
3153
3154
3155class CurrentTime(Func):
3156    arg_types = {"this": False}
3157
3158
3159class CurrentTimestamp(Func):
3160    arg_types = {"this": False}
3161
3162
3163class DateAdd(Func, TimeUnit):
3164    arg_types = {"this": True, "expression": True, "unit": False}
3165
3166
3167class DateSub(Func, TimeUnit):
3168    arg_types = {"this": True, "expression": True, "unit": False}
3169
3170
3171class DateDiff(Func, TimeUnit):
3172    arg_types = {"this": True, "expression": True, "unit": False}
3173
3174
3175class DateTrunc(Func):
3176    arg_types = {"unit": True, "this": True, "zone": False}
3177
3178
3179class DatetimeAdd(Func, TimeUnit):
3180    arg_types = {"this": True, "expression": True, "unit": False}
3181
3182
3183class DatetimeSub(Func, TimeUnit):
3184    arg_types = {"this": True, "expression": True, "unit": False}
3185
3186
3187class DatetimeDiff(Func, TimeUnit):
3188    arg_types = {"this": True, "expression": True, "unit": False}
3189
3190
3191class DatetimeTrunc(Func, TimeUnit):
3192    arg_types = {"this": True, "unit": True, "zone": False}
3193
3194
3195class DayOfWeek(Func):
3196    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
3197
3198
3199class DayOfMonth(Func):
3200    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
3201
3202
3203class DayOfYear(Func):
3204    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
3205
3206
3207class WeekOfYear(Func):
3208    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
3209
3210
3211class LastDateOfMonth(Func):
3212    pass
3213
3214
3215class Extract(Func):
3216    arg_types = {"this": True, "expression": True}
3217
3218
3219class TimestampAdd(Func, TimeUnit):
3220    arg_types = {"this": True, "expression": True, "unit": False}
3221
3222
3223class TimestampSub(Func, TimeUnit):
3224    arg_types = {"this": True, "expression": True, "unit": False}
3225
3226
3227class TimestampDiff(Func, TimeUnit):
3228    arg_types = {"this": True, "expression": True, "unit": False}
3229
3230
3231class TimestampTrunc(Func, TimeUnit):
3232    arg_types = {"this": True, "unit": True, "zone": False}
3233
3234
3235class TimeAdd(Func, TimeUnit):
3236    arg_types = {"this": True, "expression": True, "unit": False}
3237
3238
3239class TimeSub(Func, TimeUnit):
3240    arg_types = {"this": True, "expression": True, "unit": False}
3241
3242
3243class TimeDiff(Func, TimeUnit):
3244    arg_types = {"this": True, "expression": True, "unit": False}
3245
3246
3247class TimeTrunc(Func, TimeUnit):
3248    arg_types = {"this": True, "unit": True, "zone": False}
3249
3250
3251class DateFromParts(Func):
3252    _sql_names = ["DATEFROMPARTS"]
3253    arg_types = {"year": True, "month": True, "day": True}
3254
3255
3256class DateStrToDate(Func):
3257    pass
3258
3259
3260class DateToDateStr(Func):
3261    pass
3262
3263
3264class DateToDi(Func):
3265    pass
3266
3267
3268class Day(Func):
3269    pass
3270
3271
3272class Decode(Func):
3273    arg_types = {"this": True, "charset": True, "replace": False}
3274
3275
3276class DiToDate(Func):
3277    pass
3278
3279
3280class Encode(Func):
3281    arg_types = {"this": True, "charset": True}
3282
3283
3284class Exp(Func):
3285    pass
3286
3287
3288class Explode(Func):
3289    pass
3290
3291
3292class Floor(Func):
3293    arg_types = {"this": True, "decimals": False}
3294
3295
3296class Greatest(Func):
3297    arg_types = {"this": True, "expressions": False}
3298    is_var_len_args = True
3299
3300
3301class GroupConcat(Func):
3302    arg_types = {"this": True, "separator": False}
3303
3304
3305class Hex(Func):
3306    pass
3307
3308
3309class If(Func):
3310    arg_types = {"this": True, "true": True, "false": False}
3311
3312
3313class IfNull(Func):
3314    arg_types = {"this": True, "expression": False}
3315    _sql_names = ["IFNULL", "NVL"]
3316
3317
3318class Initcap(Func):
3319    pass
3320
3321
3322class JSONBContains(Binary):
3323    _sql_names = ["JSONB_CONTAINS"]
3324
3325
3326class JSONExtract(Binary, Func):
3327    _sql_names = ["JSON_EXTRACT"]
3328
3329
3330class JSONExtractScalar(JSONExtract):
3331    _sql_names = ["JSON_EXTRACT_SCALAR"]
3332
3333
3334class JSONBExtract(JSONExtract):
3335    _sql_names = ["JSONB_EXTRACT"]
3336
3337
3338class JSONBExtractScalar(JSONExtract):
3339    _sql_names = ["JSONB_EXTRACT_SCALAR"]
3340
3341
3342class Least(Func):
3343    arg_types = {"this": True, "expressions": False}
3344    is_var_len_args = True
3345
3346
3347class Length(Func):
3348    pass
3349
3350
3351class Levenshtein(Func):
3352    arg_types = {
3353        "this": True,
3354        "expression": False,
3355        "ins_cost": False,
3356        "del_cost": False,
3357        "sub_cost": False,
3358    }
3359
3360
3361class Ln(Func):
3362    pass
3363
3364
3365class Log(Func):
3366    arg_types = {"this": True, "expression": False}
3367
3368
3369class Log2(Func):
3370    pass
3371
3372
3373class Log10(Func):
3374    pass
3375
3376
3377class LogicalOr(AggFunc):
3378    _sql_names = ["LOGICAL_OR", "BOOL_OR"]
3379
3380
3381class Lower(Func):
3382    _sql_names = ["LOWER", "LCASE"]
3383
3384
3385class Map(Func):
3386    arg_types = {"keys": False, "values": False}
3387
3388
3389class VarMap(Func):
3390    arg_types = {"keys": True, "values": True}
3391    is_var_len_args = True
3392
3393
3394class Matches(Func):
3395    """Oracle/Snowflake decode.
3396    https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm
3397    Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)
3398    """
3399
3400    arg_types = {"this": True, "expressions": True}
3401    is_var_len_args = True
3402
3403
3404class Max(AggFunc):
3405    arg_types = {"this": True, "expression": False}
3406
3407
3408class Min(AggFunc):
3409    arg_types = {"this": True, "expression": False}
3410
3411
3412class Month(Func):
3413    pass
3414
3415
3416class Nvl2(Func):
3417    arg_types = {"this": True, "true": True, "false": False}
3418
3419
3420class Posexplode(Func):
3421    pass
3422
3423
3424class Pow(Binary, Func):
3425    _sql_names = ["POWER", "POW"]
3426
3427
3428class PercentileCont(AggFunc):
3429    pass
3430
3431
3432class PercentileDisc(AggFunc):
3433    pass
3434
3435
3436class Quantile(AggFunc):
3437    arg_types = {"this": True, "quantile": True}
3438
3439
3440# Clickhouse-specific:
3441# https://clickhouse.com/docs/en/sql-reference/aggregate-functions/reference/quantiles/#quantiles
3442class Quantiles(AggFunc):
3443    arg_types = {"parameters": True, "expressions": True}
3444
3445
3446class QuantileIf(AggFunc):
3447    arg_types = {"parameters": True, "expressions": True}
3448
3449
3450class ApproxQuantile(Quantile):
3451    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
3452
3453
3454class ReadCSV(Func):
3455    _sql_names = ["READ_CSV"]
3456    is_var_len_args = True
3457    arg_types = {"this": True, "expressions": False}
3458
3459
3460class Reduce(Func):
3461    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
3462
3463
3464class RegexpExtract(Func):
3465    arg_types = {
3466        "this": True,
3467        "expression": True,
3468        "position": False,
3469        "occurrence": False,
3470        "group": False,
3471    }
3472
3473
3474class RegexpLike(Func):
3475    arg_types = {"this": True, "expression": True, "flag": False}
3476
3477
3478class RegexpILike(Func):
3479    arg_types = {"this": True, "expression": True, "flag": False}
3480
3481
3482class RegexpSplit(Func):
3483    arg_types = {"this": True, "expression": True}
3484
3485
3486class Repeat(Func):
3487    arg_types = {"this": True, "times": True}
3488
3489
3490class Round(Func):
3491    arg_types = {"this": True, "decimals": False}
3492
3493
3494class RowNumber(Func):
3495    arg_types: t.Dict[str, t.Any] = {}
3496
3497
3498class SafeDivide(Func):
3499    arg_types = {"this": True, "expression": True}
3500
3501
3502class SetAgg(AggFunc):
3503    pass
3504
3505
3506class SortArray(Func):
3507    arg_types = {"this": True, "asc": False}
3508
3509
3510class Split(Func):
3511    arg_types = {"this": True, "expression": True, "limit": False}
3512
3513
3514# Start may be omitted in the case of postgres
3515# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6
3516class Substring(Func):
3517    arg_types = {"this": True, "start": False, "length": False}
3518
3519
3520class StrPosition(Func):
3521    arg_types = {
3522        "this": True,
3523        "substr": True,
3524        "position": False,
3525        "instance": False,
3526    }
3527
3528
3529class StrToDate(Func):
3530    arg_types = {"this": True, "format": True}
3531
3532
3533class StrToTime(Func):
3534    arg_types = {"this": True, "format": True}
3535
3536
3537# Spark allows unix_timestamp()
3538# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html
3539class StrToUnix(Func):
3540    arg_types = {"this": False, "format": False}
3541
3542
3543class NumberToStr(Func):
3544    arg_types = {"this": True, "format": True}
3545
3546
3547class Struct(Func):
3548    arg_types = {"expressions": True}
3549    is_var_len_args = True
3550
3551
3552class StructExtract(Func):
3553    arg_types = {"this": True, "expression": True}
3554
3555
3556class Sum(AggFunc):
3557    pass
3558
3559
3560class Sqrt(Func):
3561    pass
3562
3563
3564class Stddev(AggFunc):
3565    pass
3566
3567
3568class StddevPop(AggFunc):
3569    pass
3570
3571
3572class StddevSamp(AggFunc):
3573    pass
3574
3575
3576class TimeToStr(Func):
3577    arg_types = {"this": True, "format": True}
3578
3579
3580class TimeToTimeStr(Func):
3581    pass
3582
3583
3584class TimeToUnix(Func):
3585    pass
3586
3587
3588class TimeStrToDate(Func):
3589    pass
3590
3591
3592class TimeStrToTime(Func):
3593    pass
3594
3595
3596class TimeStrToUnix(Func):
3597    pass
3598
3599
3600class Trim(Func):
3601    arg_types = {
3602        "this": True,
3603        "expression": False,
3604        "position": False,
3605        "collation": False,
3606    }
3607
3608
3609class TsOrDsAdd(Func, TimeUnit):
3610    arg_types = {"this": True, "expression": True, "unit": False}
3611
3612
3613class TsOrDsToDateStr(Func):
3614    pass
3615
3616
3617class TsOrDsToDate(Func):
3618    arg_types = {"this": True, "format": False}
3619
3620
3621class TsOrDiToDi(Func):
3622    pass
3623
3624
3625class Unhex(Func):
3626    pass
3627
3628
3629class UnixToStr(Func):
3630    arg_types = {"this": True, "format": False}
3631
3632
3633# https://prestodb.io/docs/current/functions/datetime.html
3634# presto has weird zone/hours/minutes
3635class UnixToTime(Func):
3636    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
3637
3638    SECONDS = Literal.string("seconds")
3639    MILLIS = Literal.string("millis")
3640    MICROS = Literal.string("micros")
3641
3642
3643class UnixToTimeStr(Func):
3644    pass
3645
3646
3647class Upper(Func):
3648    _sql_names = ["UPPER", "UCASE"]
3649
3650
3651class Variance(AggFunc):
3652    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
3653
3654
3655class VariancePop(AggFunc):
3656    _sql_names = ["VARIANCE_POP", "VAR_POP"]
3657
3658
3659class Week(Func):
3660    arg_types = {"this": True, "mode": False}
3661
3662
3663class XMLTable(Func):
3664    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
3665
3666
3667class Year(Func):
3668    pass
3669
3670
3671class Use(Expression):
3672    arg_types = {"this": True, "kind": False}
3673
3674
3675class Merge(Expression):
3676    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
3677
3678
3679class When(Func):
3680    arg_types = {"this": True, "then": True}
3681
3682
3683def _norm_args(expression):
3684    args = {}
3685
3686    for k, arg in expression.args.items():
3687        if isinstance(arg, list):
3688            arg = [_norm_arg(a) for a in arg]
3689            if not arg:
3690                arg = None
3691        else:
3692            arg = _norm_arg(arg)
3693
3694        if arg is not None and arg is not False:
3695            args[k] = arg
3696
3697    return args
3698
3699
3700def _norm_arg(arg):
3701    return arg.lower() if isinstance(arg, str) else arg
3702
3703
3704ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func))
3705
3706
3707# Helpers
3708def maybe_parse(
3709    sql_or_expression: str | Expression,
3710    *,
3711    into: t.Optional[IntoType] = None,
3712    dialect: DialectType = None,
3713    prefix: t.Optional[str] = None,
3714    copy: bool = False,
3715    **opts,
3716) -> Expression:
3717    """Gracefully handle a possible string or expression.
3718
3719    Example:
3720        >>> maybe_parse("1")
3721        (LITERAL this: 1, is_string: False)
3722        >>> maybe_parse(to_identifier("x"))
3723        (IDENTIFIER this: x, quoted: False)
3724
3725    Args:
3726        sql_or_expression: the SQL code string or an expression
3727        into: the SQLGlot Expression to parse into
3728        dialect: the dialect used to parse the input expressions (in the case that an
3729            input expression is a SQL string).
3730        prefix: a string to prefix the sql with before it gets parsed
3731            (automatically includes a space)
3732        copy: whether or not to copy the expression.
3733        **opts: other options to use to parse the input expressions (again, in the case
3734            that an input expression is a SQL string).
3735
3736    Returns:
3737        Expression: the parsed or given expression.
3738    """
3739    if isinstance(sql_or_expression, Expression):
3740        if copy:
3741            return sql_or_expression.copy()
3742        return sql_or_expression
3743
3744    import sqlglot
3745
3746    sql = str(sql_or_expression)
3747    if prefix:
3748        sql = f"{prefix} {sql}"
3749    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
3750
3751
3752def _maybe_copy(instance, copy=True):
3753    return instance.copy() if copy else instance
3754
3755
3756def _is_wrong_expression(expression, into):
3757    return isinstance(expression, Expression) and not isinstance(expression, into)
3758
3759
3760def _apply_builder(
3761    expression,
3762    instance,
3763    arg,
3764    copy=True,
3765    prefix=None,
3766    into=None,
3767    dialect=None,
3768    **opts,
3769):
3770    if _is_wrong_expression(expression, into):
3771        expression = into(this=expression)
3772    instance = _maybe_copy(instance, copy)
3773    expression = maybe_parse(
3774        sql_or_expression=expression,
3775        prefix=prefix,
3776        into=into,
3777        dialect=dialect,
3778        **opts,
3779    )
3780    instance.set(arg, expression)
3781    return instance
3782
3783
3784def _apply_child_list_builder(
3785    *expressions,
3786    instance,
3787    arg,
3788    append=True,
3789    copy=True,
3790    prefix=None,
3791    into=None,
3792    dialect=None,
3793    properties=None,
3794    **opts,
3795):
3796    instance = _maybe_copy(instance, copy)
3797    parsed = []
3798    for expression in expressions:
3799        if _is_wrong_expression(expression, into):
3800            expression = into(expressions=[expression])
3801        expression = maybe_parse(
3802            expression,
3803            into=into,
3804            dialect=dialect,
3805            prefix=prefix,
3806            **opts,
3807        )
3808        parsed.extend(expression.expressions)
3809
3810    existing = instance.args.get(arg)
3811    if append and existing:
3812        parsed = existing.expressions + parsed
3813
3814    child = into(expressions=parsed)
3815    for k, v in (properties or {}).items():
3816        child.set(k, v)
3817    instance.set(arg, child)
3818    return instance
3819
3820
3821def _apply_list_builder(
3822    *expressions,
3823    instance,
3824    arg,
3825    append=True,
3826    copy=True,
3827    prefix=None,
3828    into=None,
3829    dialect=None,
3830    **opts,
3831):
3832    inst = _maybe_copy(instance, copy)
3833
3834    expressions = [
3835        maybe_parse(
3836            sql_or_expression=expression,
3837            into=into,
3838            prefix=prefix,
3839            dialect=dialect,
3840            **opts,
3841        )
3842        for expression in expressions
3843    ]
3844
3845    existing_expressions = inst.args.get(arg)
3846    if append and existing_expressions:
3847        expressions = existing_expressions + expressions
3848
3849    inst.set(arg, expressions)
3850    return inst
3851
3852
3853def _apply_conjunction_builder(
3854    *expressions,
3855    instance,
3856    arg,
3857    into=None,
3858    append=True,
3859    copy=True,
3860    dialect=None,
3861    **opts,
3862):
3863    expressions = [exp for exp in expressions if exp is not None and exp != ""]
3864    if not expressions:
3865        return instance
3866
3867    inst = _maybe_copy(instance, copy)
3868
3869    existing = inst.args.get(arg)
3870    if append and existing is not None:
3871        expressions = [existing.this if into else existing] + list(expressions)
3872
3873    node = and_(*expressions, dialect=dialect, **opts)
3874
3875    inst.set(arg, into(this=node) if into else node)
3876    return inst
3877
3878
3879def _combine(expressions, operator, dialect=None, **opts):
3880    expressions = [condition(expression, dialect=dialect, **opts) for expression in expressions]
3881    this = expressions[0]
3882    if expressions[1:]:
3883        this = _wrap_operator(this)
3884    for expression in expressions[1:]:
3885        this = operator(this=this, expression=_wrap_operator(expression))
3886    return this
3887
3888
3889def _wrap_operator(expression):
3890    if isinstance(expression, (And, Or, Not)):
3891        expression = Paren(this=expression)
3892    return expression
3893
3894
3895def union(left, right, distinct=True, dialect=None, **opts):
3896    """
3897    Initializes a syntax tree from one UNION expression.
3898
3899    Example:
3900        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
3901        'SELECT * FROM foo UNION SELECT * FROM bla'
3902
3903    Args:
3904        left (str | Expression): the SQL code string corresponding to the left-hand side.
3905            If an `Expression` instance is passed, it will be used as-is.
3906        right (str | Expression): the SQL code string corresponding to the right-hand side.
3907            If an `Expression` instance is passed, it will be used as-is.
3908        distinct (bool): set the DISTINCT flag if and only if this is true.
3909        dialect (str): the dialect used to parse the input expression.
3910        opts (kwargs): other options to use to parse the input expressions.
3911    Returns:
3912        Union: the syntax tree for the UNION expression.
3913    """
3914    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3915    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3916
3917    return Union(this=left, expression=right, distinct=distinct)
3918
3919
3920def intersect(left, right, distinct=True, dialect=None, **opts):
3921    """
3922    Initializes a syntax tree from one INTERSECT expression.
3923
3924    Example:
3925        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
3926        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
3927
3928    Args:
3929        left (str | Expression): the SQL code string corresponding to the left-hand side.
3930            If an `Expression` instance is passed, it will be used as-is.
3931        right (str | Expression): the SQL code string corresponding to the right-hand side.
3932            If an `Expression` instance is passed, it will be used as-is.
3933        distinct (bool): set the DISTINCT flag if and only if this is true.
3934        dialect (str): the dialect used to parse the input expression.
3935        opts (kwargs): other options to use to parse the input expressions.
3936    Returns:
3937        Intersect: the syntax tree for the INTERSECT expression.
3938    """
3939    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3940    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3941
3942    return Intersect(this=left, expression=right, distinct=distinct)
3943
3944
3945def except_(left, right, distinct=True, dialect=None, **opts):
3946    """
3947    Initializes a syntax tree from one EXCEPT expression.
3948
3949    Example:
3950        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
3951        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
3952
3953    Args:
3954        left (str | Expression): the SQL code string corresponding to the left-hand side.
3955            If an `Expression` instance is passed, it will be used as-is.
3956        right (str | Expression): the SQL code string corresponding to the right-hand side.
3957            If an `Expression` instance is passed, it will be used as-is.
3958        distinct (bool): set the DISTINCT flag if and only if this is true.
3959        dialect (str): the dialect used to parse the input expression.
3960        opts (kwargs): other options to use to parse the input expressions.
3961    Returns:
3962        Except: the syntax tree for the EXCEPT statement.
3963    """
3964    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3965    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3966
3967    return Except(this=left, expression=right, distinct=distinct)
3968
3969
3970def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select:
3971    """
3972    Initializes a syntax tree from one or multiple SELECT expressions.
3973
3974    Example:
3975        >>> select("col1", "col2").from_("tbl").sql()
3976        'SELECT col1, col2 FROM tbl'
3977
3978    Args:
3979        *expressions: the SQL code string to parse as the expressions of a
3980            SELECT statement. If an Expression instance is passed, this is used as-is.
3981        dialect: the dialect used to parse the input expressions (in the case that an
3982            input expression is a SQL string).
3983        **opts: other options to use to parse the input expressions (again, in the case
3984            that an input expression is a SQL string).
3985
3986    Returns:
3987        Select: the syntax tree for the SELECT statement.
3988    """
3989    return Select().select(*expressions, dialect=dialect, **opts)
3990
3991
3992def from_(*expressions, dialect=None, **opts) -> Select:
3993    """
3994    Initializes a syntax tree from a FROM expression.
3995
3996    Example:
3997        >>> from_("tbl").select("col1", "col2").sql()
3998        'SELECT col1, col2 FROM tbl'
3999
4000    Args:
4001        *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a
4002            SELECT statement. If an Expression instance is passed, this is used as-is.
4003        dialect (str): the dialect used to parse the input expression (in the case that the
4004            input expression is a SQL string).
4005        **opts: other options to use to parse the input expressions (again, in the case
4006            that the input expression is a SQL string).
4007
4008    Returns:
4009        Select: the syntax tree for the SELECT statement.
4010    """
4011    return Select().from_(*expressions, dialect=dialect, **opts)
4012
4013
4014def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update:
4015    """
4016    Creates an update statement.
4017
4018    Example:
4019        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
4020        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
4021
4022    Args:
4023        *properties (Dict[str, Any]): dictionary of properties to set which are
4024            auto converted to sql objects eg None -> NULL
4025        where (str): sql conditional parsed into a WHERE statement
4026        from_ (str): sql statement parsed into a FROM statement
4027        dialect (str): the dialect used to parse the input expressions.
4028        **opts: other options to use to parse the input expressions.
4029
4030    Returns:
4031        Update: the syntax tree for the UPDATE statement.
4032    """
4033    update = Update(this=maybe_parse(table, into=Table, dialect=dialect))
4034    update.set(
4035        "expressions",
4036        [
4037            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
4038            for k, v in properties.items()
4039        ],
4040    )
4041    if from_:
4042        update.set(
4043            "from",
4044            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
4045        )
4046    if isinstance(where, Condition):
4047        where = Where(this=where)
4048    if where:
4049        update.set(
4050            "where",
4051            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4052        )
4053    return update
4054
4055
4056def delete(table, where=None, dialect=None, **opts) -> Delete:
4057    """
4058    Builds a delete statement.
4059
4060    Example:
4061        >>> delete("my_table", where="id > 1").sql()
4062        'DELETE FROM my_table WHERE id > 1'
4063
4064    Args:
4065        where (str|Condition): sql conditional parsed into a WHERE statement
4066        dialect (str): the dialect used to parse the input expressions.
4067        **opts: other options to use to parse the input expressions.
4068
4069    Returns:
4070        Delete: the syntax tree for the DELETE statement.
4071    """
4072    return Delete(
4073        this=maybe_parse(table, into=Table, dialect=dialect, **opts),
4074        where=Where(this=where)
4075        if isinstance(where, Condition)
4076        else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4077    )
4078
4079
4080def condition(expression, dialect=None, **opts) -> Condition:
4081    """
4082    Initialize a logical condition expression.
4083
4084    Example:
4085        >>> condition("x=1").sql()
4086        'x = 1'
4087
4088        This is helpful for composing larger logical syntax trees:
4089        >>> where = condition("x=1")
4090        >>> where = where.and_("y=1")
4091        >>> Select().from_("tbl").select("*").where(where).sql()
4092        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
4093
4094    Args:
4095        *expression (str | Expression): the SQL code string to parse.
4096            If an Expression instance is passed, this is used as-is.
4097        dialect (str): the dialect used to parse the input expression (in the case that the
4098            input expression is a SQL string).
4099        **opts: other options to use to parse the input expressions (again, in the case
4100            that the input expression is a SQL string).
4101
4102    Returns:
4103        Condition: the expression
4104    """
4105    return maybe_parse(  # type: ignore
4106        expression,
4107        into=Condition,
4108        dialect=dialect,
4109        **opts,
4110    )
4111
4112
4113def and_(*expressions, dialect=None, **opts) -> And:
4114    """
4115    Combine multiple conditions with an AND logical operator.
4116
4117    Example:
4118        >>> and_("x=1", and_("y=1", "z=1")).sql()
4119        'x = 1 AND (y = 1 AND z = 1)'
4120
4121    Args:
4122        *expressions (str | Expression): the SQL code strings to parse.
4123            If an Expression instance is passed, this is used as-is.
4124        dialect (str): the dialect used to parse the input expression.
4125        **opts: other options to use to parse the input expressions.
4126
4127    Returns:
4128        And: the new condition
4129    """
4130    return _combine(expressions, And, dialect, **opts)
4131
4132
4133def or_(*expressions, dialect=None, **opts) -> Or:
4134    """
4135    Combine multiple conditions with an OR logical operator.
4136
4137    Example:
4138        >>> or_("x=1", or_("y=1", "z=1")).sql()
4139        'x = 1 OR (y = 1 OR z = 1)'
4140
4141    Args:
4142        *expressions (str | Expression): the SQL code strings to parse.
4143            If an Expression instance is passed, this is used as-is.
4144        dialect (str): the dialect used to parse the input expression.
4145        **opts: other options to use to parse the input expressions.
4146
4147    Returns:
4148        Or: the new condition
4149    """
4150    return _combine(expressions, Or, dialect, **opts)
4151
4152
4153def not_(expression, dialect=None, **opts) -> Not:
4154    """
4155    Wrap a condition with a NOT operator.
4156
4157    Example:
4158        >>> not_("this_suit='black'").sql()
4159        "NOT this_suit = 'black'"
4160
4161    Args:
4162        expression (str | Expression): the SQL code strings to parse.
4163            If an Expression instance is passed, this is used as-is.
4164        dialect (str): the dialect used to parse the input expression.
4165        **opts: other options to use to parse the input expressions.
4166
4167    Returns:
4168        Not: the new condition
4169    """
4170    this = condition(
4171        expression,
4172        dialect=dialect,
4173        **opts,
4174    )
4175    return Not(this=_wrap_operator(this))
4176
4177
4178def paren(expression) -> Paren:
4179    return Paren(this=expression)
4180
4181
4182SAFE_IDENTIFIER_RE = re.compile(r"^[_a-zA-Z][\w]*$")
4183
4184
4185@t.overload
4186def to_identifier(name: None, quoted: t.Optional[bool] = None) -> None:
4187    ...
4188
4189
4190@t.overload
4191def to_identifier(name: str | Identifier, quoted: t.Optional[bool] = None) -> Identifier:
4192    ...
4193
4194
4195def to_identifier(name, quoted=None):
4196    """Builds an identifier.
4197
4198    Args:
4199        name: The name to turn into an identifier.
4200        quoted: Whether or not force quote the identifier.
4201
4202    Returns:
4203        The identifier ast node.
4204    """
4205
4206    if name is None:
4207        return None
4208
4209    if isinstance(name, Identifier):
4210        identifier = name
4211    elif isinstance(name, str):
4212        identifier = Identifier(
4213            this=name,
4214            quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted,
4215        )
4216    else:
4217        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
4218    return identifier
4219
4220
4221INTERVAL_STRING_RE = re.compile(r"\s*([0-9]+)\s*([a-zA-Z]+)\s*")
4222
4223
4224def to_interval(interval: str | Literal) -> Interval:
4225    """Builds an interval expression from a string like '1 day' or '5 months'."""
4226    if isinstance(interval, Literal):
4227        if not interval.is_string:
4228            raise ValueError("Invalid interval string.")
4229
4230        interval = interval.this
4231
4232    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
4233
4234    if not interval_parts:
4235        raise ValueError("Invalid interval string.")
4236
4237    return Interval(
4238        this=Literal.string(interval_parts.group(1)),
4239        unit=Var(this=interval_parts.group(2)),
4240    )
4241
4242
4243@t.overload
4244def to_table(sql_path: str | Table, **kwargs) -> Table:
4245    ...
4246
4247
4248@t.overload
4249def to_table(sql_path: None, **kwargs) -> None:
4250    ...
4251
4252
4253def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]:
4254    """
4255    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
4256    If a table is passed in then that table is returned.
4257
4258    Args:
4259        sql_path: a `[catalog].[schema].[table]` string.
4260
4261    Returns:
4262        A table expression.
4263    """
4264    if sql_path is None or isinstance(sql_path, Table):
4265        return sql_path
4266    if not isinstance(sql_path, str):
4267        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
4268
4269    catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3))
4270    return Table(this=table_name, db=db, catalog=catalog, **kwargs)
4271
4272
4273def to_column(sql_path: str | Column, **kwargs) -> Column:
4274    """
4275    Create a column from a `[table].[column]` sql path. Schema is optional.
4276
4277    If a column is passed in then that column is returned.
4278
4279    Args:
4280        sql_path: `[table].[column]` string
4281    Returns:
4282        Table: A column expression
4283    """
4284    if sql_path is None or isinstance(sql_path, Column):
4285        return sql_path
4286    if not isinstance(sql_path, str):
4287        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
4288    table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2))
4289    return Column(this=column_name, table=table_name, **kwargs)
4290
4291
4292def alias_(
4293    expression: str | Expression,
4294    alias: str | Identifier,
4295    table: bool | t.Sequence[str | Identifier] = False,
4296    quoted: t.Optional[bool] = None,
4297    dialect: DialectType = None,
4298    **opts,
4299):
4300    """Create an Alias expression.
4301
4302    Example:
4303        >>> alias_('foo', 'bar').sql()
4304        'foo AS bar'
4305
4306        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
4307        '(SELECT 1, 2) AS bar(a, b)'
4308
4309    Args:
4310        expression: the SQL code strings to parse.
4311            If an Expression instance is passed, this is used as-is.
4312        alias: the alias name to use. If the name has
4313            special characters it is quoted.
4314        table: Whether or not to create a table alias, can also be a list of columns.
4315        quoted: whether or not to quote the alias
4316        dialect: the dialect used to parse the input expression.
4317        **opts: other options to use to parse the input expressions.
4318
4319    Returns:
4320        Alias: the aliased expression
4321    """
4322    exp = maybe_parse(expression, dialect=dialect, **opts)
4323    alias = to_identifier(alias, quoted=quoted)
4324
4325    if table:
4326        table_alias = TableAlias(this=alias)
4327        exp.set("alias", table_alias)
4328
4329        if not isinstance(table, bool):
4330            for column in table:
4331                table_alias.append("columns", to_identifier(column, quoted=quoted))
4332
4333        return exp
4334
4335    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
4336    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
4337    # for the complete Window expression.
4338    #
4339    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
4340
4341    if "alias" in exp.arg_types and not isinstance(exp, Window):
4342        exp = exp.copy()
4343        exp.set("alias", alias)
4344        return exp
4345    return Alias(this=exp, alias=alias)
4346
4347
4348def subquery(expression, alias=None, dialect=None, **opts):
4349    """
4350    Build a subquery expression.
4351
4352    Example:
4353        >>> subquery('select x from tbl', 'bar').select('x').sql()
4354        'SELECT x FROM (SELECT x FROM tbl) AS bar'
4355
4356    Args:
4357        expression (str | Expression): the SQL code strings to parse.
4358            If an Expression instance is passed, this is used as-is.
4359        alias (str | Expression): the alias name to use.
4360        dialect (str): the dialect used to parse the input expression.
4361        **opts: other options to use to parse the input expressions.
4362
4363    Returns:
4364        Select: a new select with the subquery expression included
4365    """
4366
4367    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
4368    return Select().from_(expression, dialect=dialect, **opts)
4369
4370
4371def column(
4372    col: str | Identifier,
4373    table: t.Optional[str | Identifier] = None,
4374    schema: t.Optional[str | Identifier] = None,
4375    quoted: t.Optional[bool] = None,
4376) -> Column:
4377    """
4378    Build a Column.
4379
4380    Args:
4381        col: column name
4382        table: table name
4383        schema: schema name
4384        quoted: whether or not to force quote each part
4385    Returns:
4386        Column: column instance
4387    """
4388    return Column(
4389        this=to_identifier(col, quoted=quoted),
4390        table=to_identifier(table, quoted=quoted),
4391        schema=to_identifier(schema, quoted=quoted),
4392    )
4393
4394
4395def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast:
4396    """Cast an expression to a data type.
4397
4398    Example:
4399        >>> cast('x + 1', 'int').sql()
4400        'CAST(x + 1 AS INT)'
4401
4402    Args:
4403        expression: The expression to cast.
4404        to: The datatype to cast to.
4405
4406    Returns:
4407        A cast node.
4408    """
4409    expression = maybe_parse(expression, **opts)
4410    return Cast(this=expression, to=DataType.build(to, **opts))
4411
4412
4413def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table:
4414    """Build a Table.
4415
4416    Args:
4417        table (str | Expression): column name
4418        db (str | Expression): db name
4419        catalog (str | Expression): catalog name
4420
4421    Returns:
4422        Table: table instance
4423    """
4424    return Table(
4425        this=to_identifier(table, quoted=quoted),
4426        db=to_identifier(db, quoted=quoted),
4427        catalog=to_identifier(catalog, quoted=quoted),
4428        alias=TableAlias(this=to_identifier(alias)) if alias else None,
4429    )
4430
4431
4432def values(
4433    values: t.Iterable[t.Tuple[t.Any, ...]],
4434    alias: t.Optional[str] = None,
4435    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
4436) -> Values:
4437    """Build VALUES statement.
4438
4439    Example:
4440        >>> values([(1, '2')]).sql()
4441        "VALUES (1, '2')"
4442
4443    Args:
4444        values: values statements that will be converted to SQL
4445        alias: optional alias
4446        columns: Optional list of ordered column names or ordered dictionary of column names to types.
4447         If either are provided then an alias is also required.
4448         If a dictionary is provided then the first column of the values will be casted to the expected type
4449         in order to help with type inference.
4450
4451    Returns:
4452        Values: the Values expression object
4453    """
4454    if columns and not alias:
4455        raise ValueError("Alias is required when providing columns")
4456    table_alias = (
4457        TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
4458        if columns
4459        else TableAlias(this=to_identifier(alias) if alias else None)
4460    )
4461    expressions = [convert(tup) for tup in values]
4462    if columns and isinstance(columns, dict):
4463        types = list(columns.values())
4464        expressions[0].set(
4465            "expressions",
4466            [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)],
4467        )
4468    return Values(
4469        expressions=expressions,
4470        alias=table_alias,
4471    )
4472
4473
4474def var(name: t.Optional[str | Expression]) -> Var:
4475    """Build a SQL variable.
4476
4477    Example:
4478        >>> repr(var('x'))
4479        '(VAR this: x)'
4480
4481        >>> repr(var(column('x', table='y')))
4482        '(VAR this: x)'
4483
4484    Args:
4485        name: The name of the var or an expression who's name will become the var.
4486
4487    Returns:
4488        The new variable node.
4489    """
4490    if not name:
4491        raise ValueError(f"Cannot convert empty name into var.")
4492
4493    if isinstance(name, Expression):
4494        name = name.name
4495    return Var(this=name)
4496
4497
4498def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
4499    """Build ALTER TABLE... RENAME... expression
4500
4501    Args:
4502        old_name: The old name of the table
4503        new_name: The new name of the table
4504
4505    Returns:
4506        Alter table expression
4507    """
4508    old_table = to_table(old_name)
4509    new_table = to_table(new_name)
4510    return AlterTable(
4511        this=old_table,
4512        actions=[
4513            RenameTable(this=new_table),
4514        ],
4515    )
4516
4517
4518def convert(value) -> Expression:
4519    """Convert a python value into an expression object.
4520
4521    Raises an error if a conversion is not possible.
4522
4523    Args:
4524        value (Any): a python object
4525
4526    Returns:
4527        Expression: the equivalent expression object
4528    """
4529    if isinstance(value, Expression):
4530        return value
4531    if value is None:
4532        return NULL
4533    if isinstance(value, bool):
4534        return Boolean(this=value)
4535    if isinstance(value, str):
4536        return Literal.string(value)
4537    if isinstance(value, float) and math.isnan(value):
4538        return NULL
4539    if isinstance(value, numbers.Number):
4540        return Literal.number(value)
4541    if isinstance(value, tuple):
4542        return Tuple(expressions=[convert(v) for v in value])
4543    if isinstance(value, list):
4544        return Array(expressions=[convert(v) for v in value])
4545    if isinstance(value, dict):
4546        return Map(
4547            keys=[convert(k) for k in value],
4548            values=[convert(v) for v in value.values()],
4549        )
4550    if isinstance(value, datetime.datetime):
4551        datetime_literal = Literal.string(
4552            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
4553        )
4554        return TimeStrToTime(this=datetime_literal)
4555    if isinstance(value, datetime.date):
4556        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
4557        return DateStrToDate(this=date_literal)
4558    raise ValueError(f"Cannot convert {value}")
4559
4560
4561def replace_children(expression, fun):
4562    """
4563    Replace children of an expression with the result of a lambda fun(child) -> exp.
4564    """
4565    for k, v in expression.args.items():
4566        is_list_arg = isinstance(v, list)
4567
4568        child_nodes = v if is_list_arg else [v]
4569        new_child_nodes = []
4570
4571        for cn in child_nodes:
4572            if isinstance(cn, Expression):
4573                for child_node in ensure_collection(fun(cn)):
4574                    new_child_nodes.append(child_node)
4575                    child_node.parent = expression
4576                    child_node.arg_key = k
4577            else:
4578                new_child_nodes.append(cn)
4579
4580        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)
4581
4582
4583def column_table_names(expression):
4584    """
4585    Return all table names referenced through columns in an expression.
4586
4587    Example:
4588        >>> import sqlglot
4589        >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
4590        ['c', 'a']
4591
4592    Args:
4593        expression (sqlglot.Expression): expression to find table names
4594
4595    Returns:
4596        list: A list of unique names
4597    """
4598    return list(dict.fromkeys(column.table for column in expression.find_all(Column)))
4599
4600
4601def table_name(table) -> str:
4602    """Get the full name of a table as a string.
4603
4604    Args:
4605        table (exp.Table | str): table expression node or string.
4606
4607    Examples:
4608        >>> from sqlglot import exp, parse_one
4609        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
4610        'a.b.c'
4611
4612    Returns:
4613        The table name.
4614    """
4615
4616    table = maybe_parse(table, into=Table)
4617
4618    if not table:
4619        raise ValueError(f"Cannot parse {table}")
4620
4621    return ".".join(
4622        part
4623        for part in (
4624            table.text("catalog"),
4625            table.text("db"),
4626            table.name,
4627        )
4628        if part
4629    )
4630
4631
4632def replace_tables(expression, mapping):
4633    """Replace all tables in expression according to the mapping.
4634
4635    Args:
4636        expression (sqlglot.Expression): expression node to be transformed and replaced.
4637        mapping (Dict[str, str]): mapping of table names.
4638
4639    Examples:
4640        >>> from sqlglot import exp, parse_one
4641        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
4642        'SELECT * FROM c'
4643
4644    Returns:
4645        The mapped expression.
4646    """
4647
4648    def _replace_tables(node):
4649        if isinstance(node, Table):
4650            new_name = mapping.get(table_name(node))
4651            if new_name:
4652                return to_table(
4653                    new_name,
4654                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
4655                )
4656        return node
4657
4658    return expression.transform(_replace_tables)
4659
4660
4661def replace_placeholders(expression, *args, **kwargs):
4662    """Replace placeholders in an expression.
4663
4664    Args:
4665        expression (sqlglot.Expression): expression node to be transformed and replaced.
4666        args: positional names that will substitute unnamed placeholders in the given order.
4667        kwargs: keyword arguments that will substitute named placeholders.
4668
4669    Examples:
4670        >>> from sqlglot import exp, parse_one
4671        >>> replace_placeholders(
4672        ...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
4673        ... ).sql()
4674        'SELECT * FROM foo WHERE a = b'
4675
4676    Returns:
4677        The mapped expression.
4678    """
4679
4680    def _replace_placeholders(node, args, **kwargs):
4681        if isinstance(node, Placeholder):
4682            if node.name:
4683                new_name = kwargs.get(node.name)
4684                if new_name:
4685                    return to_identifier(new_name)
4686            else:
4687                try:
4688                    return to_identifier(next(args))
4689                except StopIteration:
4690                    pass
4691        return node
4692
4693    return expression.transform(_replace_placeholders, iter(args), **kwargs)
4694
4695
4696def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression:
4697    """Transforms an expression by expanding all referenced sources into subqueries.
4698
4699    Examples:
4700        >>> from sqlglot import parse_one
4701        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
4702        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
4703
4704    Args:
4705        expression: The expression to expand.
4706        sources: A dictionary of name to Subqueryables.
4707        copy: Whether or not to copy the expression during transformation. Defaults to True.
4708
4709    Returns:
4710        The transformed expression.
4711    """
4712
4713    def _expand(node: Expression):
4714        if isinstance(node, Table):
4715            name = table_name(node)
4716            source = sources.get(name)
4717            if source:
4718                subquery = source.subquery(node.alias or name)
4719                subquery.comments = [f"source: {name}"]
4720                return subquery
4721        return node
4722
4723    return expression.transform(_expand, copy=copy)
4724
4725
4726def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
4727    """
4728    Returns a Func expression.
4729
4730    Examples:
4731        >>> func("abs", 5).sql()
4732        'ABS(5)'
4733
4734        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
4735        'CAST(5 AS DOUBLE)'
4736
4737    Args:
4738        name: the name of the function to build.
4739        args: the args used to instantiate the function of interest.
4740        dialect: the source dialect.
4741        kwargs: the kwargs used to instantiate the function of interest.
4742
4743    Note:
4744        The arguments `args` and `kwargs` are mutually exclusive.
4745
4746    Returns:
4747        An instance of the function of interest, or an anonymous function, if `name` doesn't
4748        correspond to an existing `sqlglot.expressions.Func` class.
4749    """
4750    if args and kwargs:
4751        raise ValueError("Can't use both args and kwargs to instantiate a function.")
4752
4753    from sqlglot.dialects.dialect import Dialect
4754
4755    args = tuple(convert(arg) for arg in args)
4756    kwargs = {key: convert(value) for key, value in kwargs.items()}
4757
4758    parser = Dialect.get_or_raise(dialect)().parser()
4759    from_args_list = parser.FUNCTIONS.get(name.upper())
4760
4761    if from_args_list:
4762        function = from_args_list(args) if args else from_args_list.__self__(**kwargs)  # type: ignore
4763    else:
4764        kwargs = kwargs or {"expressions": args}
4765        function = Anonymous(this=name, **kwargs)
4766
4767    for error_message in function.error_messages(args):
4768        raise ValueError(error_message)
4769
4770    return function
4771
4772
4773def true():
4774    """
4775    Returns a true Boolean expression.
4776    """
4777    return Boolean(this=True)
4778
4779
4780def false():
4781    """
4782    Returns a false Boolean expression.
4783    """
4784    return Boolean(this=False)
4785
4786
4787def null():
4788    """
4789    Returns a Null expression.
4790    """
4791    return Null()
4792
4793
4794# TODO: deprecate this
4795TRUE = Boolean(this=True)
4796FALSE = Boolean(this=False)
4797NULL = Null()
class Expression:
 54class Expression(metaclass=_Expression):
 55    """
 56    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
 57    context, such as its child expressions, their names (arg keys), and whether a given child expression
 58    is optional or not.
 59
 60    Attributes:
 61        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
 62            and representing expressions as strings.
 63        arg_types: determines what arguments (child nodes) are supported by an expression. It
 64            maps arg keys to booleans that indicate whether the corresponding args are optional.
 65
 66    Example:
 67        >>> class Foo(Expression):
 68        ...     arg_types = {"this": True, "expression": False}
 69
 70        The above definition informs us that Foo is an Expression that requires an argument called
 71        "this" and may also optionally receive an argument called "expression".
 72
 73    Args:
 74        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
 75        parent: a reference to the parent expression (or None, in case of root expressions).
 76        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
 77            uses to refer to it.
 78        comments: a list of comments that are associated with a given expression. This is used in
 79            order to preserve comments when transpiling SQL code.
 80        _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
 81            optimizer, in order to enable some transformations that require type information.
 82    """
 83
 84    key = "expression"
 85    arg_types = {"this": True}
 86    __slots__ = ("args", "parent", "arg_key", "comments", "_type")
 87
 88    def __init__(self, **args: t.Any):
 89        self.args: t.Dict[str, t.Any] = args
 90        self.parent: t.Optional[Expression] = None
 91        self.arg_key: t.Optional[str] = None
 92        self.comments: t.Optional[t.List[str]] = None
 93        self._type: t.Optional[DataType] = None
 94
 95        for arg_key, value in self.args.items():
 96            self._set_parent(arg_key, value)
 97
 98    def __eq__(self, other) -> bool:
 99        return type(self) is type(other) and _norm_args(self) == _norm_args(other)
100
101    def __hash__(self) -> int:
102        return hash(
103            (
104                self.key,
105                tuple(
106                    (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items()
107                ),
108            )
109        )
110
111    @property
112    def this(self):
113        """
114        Retrieves the argument with key "this".
115        """
116        return self.args.get("this")
117
118    @property
119    def expression(self):
120        """
121        Retrieves the argument with key "expression".
122        """
123        return self.args.get("expression")
124
125    @property
126    def expressions(self):
127        """
128        Retrieves the argument with key "expressions".
129        """
130        return self.args.get("expressions") or []
131
132    def text(self, key) -> str:
133        """
134        Returns a textual representation of the argument corresponding to "key". This can only be used
135        for args that are strings or leaf Expression instances, such as identifiers and literals.
136        """
137        field = self.args.get(key)
138        if isinstance(field, str):
139            return field
140        if isinstance(field, (Identifier, Literal, Var)):
141            return field.this
142        if isinstance(field, (Star, Null)):
143            return field.name
144        return ""
145
146    @property
147    def is_string(self) -> bool:
148        """
149        Checks whether a Literal expression is a string.
150        """
151        return isinstance(self, Literal) and self.args["is_string"]
152
153    @property
154    def is_number(self) -> bool:
155        """
156        Checks whether a Literal expression is a number.
157        """
158        return isinstance(self, Literal) and not self.args["is_string"]
159
160    @property
161    def is_int(self) -> bool:
162        """
163        Checks whether a Literal expression is an integer.
164        """
165        if self.is_number:
166            try:
167                int(self.name)
168                return True
169            except ValueError:
170                pass
171        return False
172
173    @property
174    def is_star(self) -> bool:
175        """Checks whether an expression is a star."""
176        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
177
178    @property
179    def alias(self) -> str:
180        """
181        Returns the alias of the expression, or an empty string if it's not aliased.
182        """
183        if isinstance(self.args.get("alias"), TableAlias):
184            return self.args["alias"].name
185        return self.text("alias")
186
187    @property
188    def name(self) -> str:
189        return self.text("this")
190
191    @property
192    def alias_or_name(self):
193        return self.alias or self.name
194
195    @property
196    def output_name(self):
197        """
198        Name of the output column if this expression is a selection.
199
200        If the Expression has no output name, an empty string is returned.
201
202        Example:
203            >>> from sqlglot import parse_one
204            >>> parse_one("SELECT a").expressions[0].output_name
205            'a'
206            >>> parse_one("SELECT b AS c").expressions[0].output_name
207            'c'
208            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
209            ''
210        """
211        return ""
212
213    @property
214    def type(self) -> t.Optional[DataType]:
215        return self._type
216
217    @type.setter
218    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
219        if dtype and not isinstance(dtype, DataType):
220            dtype = DataType.build(dtype)
221        self._type = dtype  # type: ignore
222
223    def __deepcopy__(self, memo):
224        copy = self.__class__(**deepcopy(self.args))
225        copy.comments = self.comments
226        copy.type = self.type
227        return copy
228
229    def copy(self):
230        """
231        Returns a deep copy of the expression.
232        """
233        new = deepcopy(self)
234        new.parent = self.parent
235        for item, parent, _ in new.bfs():
236            if isinstance(item, Expression) and parent:
237                item.parent = parent
238        return new
239
240    def append(self, arg_key, value):
241        """
242        Appends value to arg_key if it's a list or sets it as a new list.
243
244        Args:
245            arg_key (str): name of the list expression arg
246            value (Any): value to append to the list
247        """
248        if not isinstance(self.args.get(arg_key), list):
249            self.args[arg_key] = []
250        self.args[arg_key].append(value)
251        self._set_parent(arg_key, value)
252
253    def set(self, arg_key, value):
254        """
255        Sets `arg_key` to `value`.
256
257        Args:
258            arg_key (str): name of the expression arg.
259            value: value to set the arg to.
260        """
261        self.args[arg_key] = value
262        self._set_parent(arg_key, value)
263
264    def _set_parent(self, arg_key, value):
265        if isinstance(value, Expression):
266            value.parent = self
267            value.arg_key = arg_key
268        elif isinstance(value, list):
269            for v in value:
270                if isinstance(v, Expression):
271                    v.parent = self
272                    v.arg_key = arg_key
273
274    @property
275    def depth(self):
276        """
277        Returns the depth of this tree.
278        """
279        if self.parent:
280            return self.parent.depth + 1
281        return 0
282
283    def find(self, *expression_types, bfs=True):
284        """
285        Returns the first node in this tree which matches at least one of
286        the specified types.
287
288        Args:
289            expression_types (type): the expression type(s) to match.
290
291        Returns:
292            The node which matches the criteria or None if no such node was found.
293        """
294        return next(self.find_all(*expression_types, bfs=bfs), None)
295
296    def find_all(self, *expression_types, bfs=True):
297        """
298        Returns a generator object which visits all nodes in this tree and only
299        yields those that match at least one of the specified expression types.
300
301        Args:
302            expression_types (type): the expression type(s) to match.
303
304        Returns:
305            The generator object.
306        """
307        for expression, _, _ in self.walk(bfs=bfs):
308            if isinstance(expression, expression_types):
309                yield expression
310
311    def find_ancestor(self, *expression_types):
312        """
313        Returns a nearest parent matching expression_types.
314
315        Args:
316            expression_types (type): the expression type(s) to match.
317
318        Returns:
319            The parent node.
320        """
321        ancestor = self.parent
322        while ancestor and not isinstance(ancestor, expression_types):
323            ancestor = ancestor.parent
324        return ancestor
325
326    @property
327    def parent_select(self):
328        """
329        Returns the parent select statement.
330        """
331        return self.find_ancestor(Select)
332
333    def walk(self, bfs=True, prune=None):
334        """
335        Returns a generator object which visits all nodes in this tree.
336
337        Args:
338            bfs (bool): if set to True the BFS traversal order will be applied,
339                otherwise the DFS traversal will be used instead.
340            prune ((node, parent, arg_key) -> bool): callable that returns True if
341                the generator should stop traversing this branch of the tree.
342
343        Returns:
344            the generator object.
345        """
346        if bfs:
347            yield from self.bfs(prune=prune)
348        else:
349            yield from self.dfs(prune=prune)
350
351    def dfs(self, parent=None, key=None, prune=None):
352        """
353        Returns a generator object which visits all nodes in this tree in
354        the DFS (Depth-first) order.
355
356        Returns:
357            The generator object.
358        """
359        parent = parent or self.parent
360        yield self, parent, key
361        if prune and prune(self, parent, key):
362            return
363
364        for k, v in self.args.items():
365            for node in ensure_collection(v):
366                if isinstance(node, Expression):
367                    yield from node.dfs(self, k, prune)
368
369    def bfs(self, prune=None):
370        """
371        Returns a generator object which visits all nodes in this tree in
372        the BFS (Breadth-first) order.
373
374        Returns:
375            The generator object.
376        """
377        queue = deque([(self, self.parent, None)])
378
379        while queue:
380            item, parent, key = queue.popleft()
381
382            yield item, parent, key
383            if prune and prune(item, parent, key):
384                continue
385
386            if isinstance(item, Expression):
387                for k, v in item.args.items():
388                    for node in ensure_collection(v):
389                        if isinstance(node, Expression):
390                            queue.append((node, item, k))
391
392    def unnest(self):
393        """
394        Returns the first non parenthesis child or self.
395        """
396        expression = self
397        while isinstance(expression, Paren):
398            expression = expression.this
399        return expression
400
401    def unalias(self):
402        """
403        Returns the inner expression if this is an Alias.
404        """
405        if isinstance(self, Alias):
406            return self.this
407        return self
408
409    def unnest_operands(self):
410        """
411        Returns unnested operands as a tuple.
412        """
413        return tuple(arg.unnest() for arg in self.args.values() if arg)
414
415    def flatten(self, unnest=True):
416        """
417        Returns a generator which yields child nodes who's parents are the same class.
418
419        A AND B AND C -> [A, B, C]
420        """
421        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
422            if not isinstance(node, self.__class__):
423                yield node.unnest() if unnest else node
424
425    def __str__(self):
426        return self.sql()
427
428    def __repr__(self):
429        return self._to_s()
430
431    def sql(self, dialect: DialectType = None, **opts) -> str:
432        """
433        Returns SQL string representation of this tree.
434
435        Args:
436            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
437            opts: other `sqlglot.generator.Generator` options.
438
439        Returns:
440            The SQL string.
441        """
442        from sqlglot.dialects import Dialect
443
444        return Dialect.get_or_raise(dialect)().generate(self, **opts)
445
446    def _to_s(self, hide_missing: bool = True, level: int = 0) -> str:
447        indent = "" if not level else "\n"
448        indent += "".join(["  "] * level)
449        left = f"({self.key.upper()} "
450
451        args: t.Dict[str, t.Any] = {
452            k: ", ".join(
453                v._to_s(hide_missing=hide_missing, level=level + 1)
454                if hasattr(v, "_to_s")
455                else str(v)
456                for v in ensure_collection(vs)
457                if v is not None
458            )
459            for k, vs in self.args.items()
460        }
461        args["comments"] = self.comments
462        args["type"] = self.type
463        args = {k: v for k, v in args.items() if v or not hide_missing}
464
465        right = ", ".join(f"{k}: {v}" for k, v in args.items())
466        right += ")"
467
468        return indent + left + right
469
470    def transform(self, fun, *args, copy=True, **kwargs):
471        """
472        Recursively visits all tree nodes (excluding already transformed ones)
473        and applies the given transformation function to each node.
474
475        Args:
476            fun (function): a function which takes a node as an argument and returns a
477                new transformed node or the same node without modifications. If the function
478                returns None, then the corresponding node will be removed from the syntax tree.
479            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
480                modified in place.
481
482        Returns:
483            The transformed tree.
484        """
485        node = self.copy() if copy else self
486        new_node = fun(node, *args, **kwargs)
487
488        if new_node is None or not isinstance(new_node, Expression):
489            return new_node
490        if new_node is not node:
491            new_node.parent = node.parent
492            return new_node
493
494        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
495        return new_node
496
497    def replace(self, expression):
498        """
499        Swap out this expression with a new expression.
500
501        For example::
502
503            >>> tree = Select().select("x").from_("tbl")
504            >>> tree.find(Column).replace(Column(this="y"))
505            (COLUMN this: y)
506            >>> tree.sql()
507            'SELECT y FROM tbl'
508
509        Args:
510            expression (Expression|None): new node
511
512        Returns:
513            The new expression or expressions.
514        """
515        if not self.parent:
516            return expression
517
518        parent = self.parent
519        self.parent = None
520
521        replace_children(parent, lambda child: expression if child is self else child)
522        return expression
523
524    def pop(self):
525        """
526        Remove this expression from its AST.
527        """
528        self.replace(None)
529
530    def assert_is(self, type_):
531        """
532        Assert that this `Expression` is an instance of `type_`.
533
534        If it is NOT an instance of `type_`, this raises an assertion error.
535        Otherwise, this returns this expression.
536
537        Examples:
538            This is useful for type security in chained expressions:
539
540            >>> import sqlglot
541            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
542            'SELECT x, z FROM y'
543        """
544        assert isinstance(self, type_)
545        return self
546
547    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
548        """
549        Checks if this expression is valid (e.g. all mandatory args are set).
550
551        Args:
552            args: a sequence of values that were used to instantiate a Func expression. This is used
553                to check that the provided arguments don't exceed the function argument limit.
554
555        Returns:
556            A list of error messages for all possible errors that were found.
557        """
558        errors: t.List[str] = []
559
560        for k in self.args:
561            if k not in self.arg_types:
562                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
563        for k, mandatory in self.arg_types.items():
564            v = self.args.get(k)
565            if mandatory and (v is None or (isinstance(v, list) and not v)):
566                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
567
568        if (
569            args
570            and isinstance(self, Func)
571            and len(args) > len(self.arg_types)
572            and not self.is_var_len_args
573        ):
574            errors.append(
575                f"The number of provided arguments ({len(args)}) is greater than "
576                f"the maximum number of supported arguments ({len(self.arg_types)})"
577            )
578
579        return errors
580
581    def dump(self):
582        """
583        Dump this Expression to a JSON-serializable dict.
584        """
585        from sqlglot.serde import dump
586
587        return dump(self)
588
589    @classmethod
590    def load(cls, obj):
591        """
592        Load a dict (as returned by `Expression.dump`) into an Expression instance.
593        """
594        from sqlglot.serde import load
595
596        return load(obj)

The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary context, such as its child expressions, their names (arg keys), and whether a given child expression is optional or not.

Attributes:
  • key: a unique key for each class in the Expression hierarchy. This is useful for hashing and representing expressions as strings.
  • arg_types: determines what arguments (child nodes) are supported by an expression. It maps arg keys to booleans that indicate whether the corresponding args are optional.
Example:
>>> class Foo(Expression):
...     arg_types = {"this": True, "expression": False}

The above definition informs us that Foo is an Expression that requires an argument called "this" and may also optionally receive an argument called "expression".

Arguments:
  • args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  • parent: a reference to the parent expression (or None, in case of root expressions).
  • arg_key: the arg key an expression is associated with, i.e. the name its parent expression uses to refer to it.
  • comments: a list of comments that are associated with a given expression. This is used in order to preserve comments when transpiling SQL code.
  • _type: the sqlglot.expressions.DataType type of an expression. This is inferred by the optimizer, in order to enable some transformations that require type information.
Expression(**args: Any)
88    def __init__(self, **args: t.Any):
89        self.args: t.Dict[str, t.Any] = args
90        self.parent: t.Optional[Expression] = None
91        self.arg_key: t.Optional[str] = None
92        self.comments: t.Optional[t.List[str]] = None
93        self._type: t.Optional[DataType] = None
94
95        for arg_key, value in self.args.items():
96            self._set_parent(arg_key, value)
this

Retrieves the argument with key "this".

expression

Retrieves the argument with key "expression".

expressions

Retrieves the argument with key "expressions".

def text(self, key) -> str:
132    def text(self, key) -> str:
133        """
134        Returns a textual representation of the argument corresponding to "key". This can only be used
135        for args that are strings or leaf Expression instances, such as identifiers and literals.
136        """
137        field = self.args.get(key)
138        if isinstance(field, str):
139            return field
140        if isinstance(field, (Identifier, Literal, Var)):
141            return field.this
142        if isinstance(field, (Star, Null)):
143            return field.name
144        return ""

Returns a textual representation of the argument corresponding to "key". This can only be used for args that are strings or leaf Expression instances, such as identifiers and literals.

is_string: bool

Checks whether a Literal expression is a string.

is_number: bool

Checks whether a Literal expression is a number.

is_int: bool

Checks whether a Literal expression is an integer.

is_star: bool

Checks whether an expression is a star.

alias: str

Returns the alias of the expression, or an empty string if it's not aliased.

output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
def copy(self):
229    def copy(self):
230        """
231        Returns a deep copy of the expression.
232        """
233        new = deepcopy(self)
234        new.parent = self.parent
235        for item, parent, _ in new.bfs():
236            if isinstance(item, Expression) and parent:
237                item.parent = parent
238        return new

Returns a deep copy of the expression.

def append(self, arg_key, value):
240    def append(self, arg_key, value):
241        """
242        Appends value to arg_key if it's a list or sets it as a new list.
243
244        Args:
245            arg_key (str): name of the list expression arg
246            value (Any): value to append to the list
247        """
248        if not isinstance(self.args.get(arg_key), list):
249            self.args[arg_key] = []
250        self.args[arg_key].append(value)
251        self._set_parent(arg_key, value)

Appends value to arg_key if it's a list or sets it as a new list.

Arguments:
  • arg_key (str): name of the list expression arg
  • value (Any): value to append to the list
def set(self, arg_key, value):
253    def set(self, arg_key, value):
254        """
255        Sets `arg_key` to `value`.
256
257        Args:
258            arg_key (str): name of the expression arg.
259            value: value to set the arg to.
260        """
261        self.args[arg_key] = value
262        self._set_parent(arg_key, value)

Sets arg_key to value.

Arguments:
  • arg_key (str): name of the expression arg.
  • value: value to set the arg to.
depth

Returns the depth of this tree.

def find(self, *expression_types, bfs=True):
283    def find(self, *expression_types, bfs=True):
284        """
285        Returns the first node in this tree which matches at least one of
286        the specified types.
287
288        Args:
289            expression_types (type): the expression type(s) to match.
290
291        Returns:
292            The node which matches the criteria or None if no such node was found.
293        """
294        return next(self.find_all(*expression_types, bfs=bfs), None)

Returns the first node in this tree which matches at least one of the specified types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The node which matches the criteria or None if no such node was found.

def find_all(self, *expression_types, bfs=True):
296    def find_all(self, *expression_types, bfs=True):
297        """
298        Returns a generator object which visits all nodes in this tree and only
299        yields those that match at least one of the specified expression types.
300
301        Args:
302            expression_types (type): the expression type(s) to match.
303
304        Returns:
305            The generator object.
306        """
307        for expression, _, _ in self.walk(bfs=bfs):
308            if isinstance(expression, expression_types):
309                yield expression

Returns a generator object which visits all nodes in this tree and only yields those that match at least one of the specified expression types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The generator object.

def find_ancestor(self, *expression_types):
311    def find_ancestor(self, *expression_types):
312        """
313        Returns a nearest parent matching expression_types.
314
315        Args:
316            expression_types (type): the expression type(s) to match.
317
318        Returns:
319            The parent node.
320        """
321        ancestor = self.parent
322        while ancestor and not isinstance(ancestor, expression_types):
323            ancestor = ancestor.parent
324        return ancestor

Returns a nearest parent matching expression_types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The parent node.

parent_select

Returns the parent select statement.

def walk(self, bfs=True, prune=None):
333    def walk(self, bfs=True, prune=None):
334        """
335        Returns a generator object which visits all nodes in this tree.
336
337        Args:
338            bfs (bool): if set to True the BFS traversal order will be applied,
339                otherwise the DFS traversal will be used instead.
340            prune ((node, parent, arg_key) -> bool): callable that returns True if
341                the generator should stop traversing this branch of the tree.
342
343        Returns:
344            the generator object.
345        """
346        if bfs:
347            yield from self.bfs(prune=prune)
348        else:
349            yield from self.dfs(prune=prune)

Returns a generator object which visits all nodes in this tree.

Arguments:
  • bfs (bool): if set to True the BFS traversal order will be applied, otherwise the DFS traversal will be used instead.
  • prune ((node, parent, arg_key) -> bool): callable that returns True if the generator should stop traversing this branch of the tree.
Returns:

the generator object.

def dfs(self, parent=None, key=None, prune=None):
351    def dfs(self, parent=None, key=None, prune=None):
352        """
353        Returns a generator object which visits all nodes in this tree in
354        the DFS (Depth-first) order.
355
356        Returns:
357            The generator object.
358        """
359        parent = parent or self.parent
360        yield self, parent, key
361        if prune and prune(self, parent, key):
362            return
363
364        for k, v in self.args.items():
365            for node in ensure_collection(v):
366                if isinstance(node, Expression):
367                    yield from node.dfs(self, k, prune)

Returns a generator object which visits all nodes in this tree in the DFS (Depth-first) order.

Returns:

The generator object.

def bfs(self, prune=None):
369    def bfs(self, prune=None):
370        """
371        Returns a generator object which visits all nodes in this tree in
372        the BFS (Breadth-first) order.
373
374        Returns:
375            The generator object.
376        """
377        queue = deque([(self, self.parent, None)])
378
379        while queue:
380            item, parent, key = queue.popleft()
381
382            yield item, parent, key
383            if prune and prune(item, parent, key):
384                continue
385
386            if isinstance(item, Expression):
387                for k, v in item.args.items():
388                    for node in ensure_collection(v):
389                        if isinstance(node, Expression):
390                            queue.append((node, item, k))

Returns a generator object which visits all nodes in this tree in the BFS (Breadth-first) order.

Returns:

The generator object.

def unnest(self):
392    def unnest(self):
393        """
394        Returns the first non parenthesis child or self.
395        """
396        expression = self
397        while isinstance(expression, Paren):
398            expression = expression.this
399        return expression

Returns the first non parenthesis child or self.

def unalias(self):
401    def unalias(self):
402        """
403        Returns the inner expression if this is an Alias.
404        """
405        if isinstance(self, Alias):
406            return self.this
407        return self

Returns the inner expression if this is an Alias.

def unnest_operands(self):
409    def unnest_operands(self):
410        """
411        Returns unnested operands as a tuple.
412        """
413        return tuple(arg.unnest() for arg in self.args.values() if arg)

Returns unnested operands as a tuple.

def flatten(self, unnest=True):
415    def flatten(self, unnest=True):
416        """
417        Returns a generator which yields child nodes who's parents are the same class.
418
419        A AND B AND C -> [A, B, C]
420        """
421        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
422            if not isinstance(node, self.__class__):
423                yield node.unnest() if unnest else node

Returns a generator which yields child nodes who's parents are the same class.

A AND B AND C -> [A, B, C]

def sql( self, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> str:
431    def sql(self, dialect: DialectType = None, **opts) -> str:
432        """
433        Returns SQL string representation of this tree.
434
435        Args:
436            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
437            opts: other `sqlglot.generator.Generator` options.
438
439        Returns:
440            The SQL string.
441        """
442        from sqlglot.dialects import Dialect
443
444        return Dialect.get_or_raise(dialect)().generate(self, **opts)

Returns SQL string representation of this tree.

Arguments:
  • dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
  • opts: other sqlglot.generator.Generator options.
Returns:

The SQL string.

def transform(self, fun, *args, copy=True, **kwargs):
470    def transform(self, fun, *args, copy=True, **kwargs):
471        """
472        Recursively visits all tree nodes (excluding already transformed ones)
473        and applies the given transformation function to each node.
474
475        Args:
476            fun (function): a function which takes a node as an argument and returns a
477                new transformed node or the same node without modifications. If the function
478                returns None, then the corresponding node will be removed from the syntax tree.
479            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
480                modified in place.
481
482        Returns:
483            The transformed tree.
484        """
485        node = self.copy() if copy else self
486        new_node = fun(node, *args, **kwargs)
487
488        if new_node is None or not isinstance(new_node, Expression):
489            return new_node
490        if new_node is not node:
491            new_node.parent = node.parent
492            return new_node
493
494        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
495        return new_node

Recursively visits all tree nodes (excluding already transformed ones) and applies the given transformation function to each node.

Arguments:
  • fun (function): a function which takes a node as an argument and returns a new transformed node or the same node without modifications. If the function returns None, then the corresponding node will be removed from the syntax tree.
  • copy (bool): if set to True a new tree instance is constructed, otherwise the tree is modified in place.
Returns:

The transformed tree.

def replace(self, expression):
497    def replace(self, expression):
498        """
499        Swap out this expression with a new expression.
500
501        For example::
502
503            >>> tree = Select().select("x").from_("tbl")
504            >>> tree.find(Column).replace(Column(this="y"))
505            (COLUMN this: y)
506            >>> tree.sql()
507            'SELECT y FROM tbl'
508
509        Args:
510            expression (Expression|None): new node
511
512        Returns:
513            The new expression or expressions.
514        """
515        if not self.parent:
516            return expression
517
518        parent = self.parent
519        self.parent = None
520
521        replace_children(parent, lambda child: expression if child is self else child)
522        return expression

Swap out this expression with a new expression.

For example::

>>> tree = Select().select("x").from_("tbl")
>>> tree.find(Column).replace(Column(this="y"))
(COLUMN this: y)
>>> tree.sql()
'SELECT y FROM tbl'
Arguments:
  • expression (Expression|None): new node
Returns:

The new expression or expressions.

def pop(self):
524    def pop(self):
525        """
526        Remove this expression from its AST.
527        """
528        self.replace(None)

Remove this expression from its AST.

def assert_is(self, type_):
530    def assert_is(self, type_):
531        """
532        Assert that this `Expression` is an instance of `type_`.
533
534        If it is NOT an instance of `type_`, this raises an assertion error.
535        Otherwise, this returns this expression.
536
537        Examples:
538            This is useful for type security in chained expressions:
539
540            >>> import sqlglot
541            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
542            'SELECT x, z FROM y'
543        """
544        assert isinstance(self, type_)
545        return self

Assert that this Expression is an instance of type_.

If it is NOT an instance of type_, this raises an assertion error. Otherwise, this returns this expression.

Examples:

This is useful for type security in chained expressions:

>>> import sqlglot
>>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
'SELECT x, z FROM y'
def error_messages(self, args: Optional[Sequence] = None) -> List[str]:
547    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
548        """
549        Checks if this expression is valid (e.g. all mandatory args are set).
550
551        Args:
552            args: a sequence of values that were used to instantiate a Func expression. This is used
553                to check that the provided arguments don't exceed the function argument limit.
554
555        Returns:
556            A list of error messages for all possible errors that were found.
557        """
558        errors: t.List[str] = []
559
560        for k in self.args:
561            if k not in self.arg_types:
562                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
563        for k, mandatory in self.arg_types.items():
564            v = self.args.get(k)
565            if mandatory and (v is None or (isinstance(v, list) and not v)):
566                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
567
568        if (
569            args
570            and isinstance(self, Func)
571            and len(args) > len(self.arg_types)
572            and not self.is_var_len_args
573        ):
574            errors.append(
575                f"The number of provided arguments ({len(args)}) is greater than "
576                f"the maximum number of supported arguments ({len(self.arg_types)})"
577            )
578
579        return errors

Checks if this expression is valid (e.g. all mandatory args are set).

Arguments:
  • args: a sequence of values that were used to instantiate a Func expression. This is used to check that the provided arguments don't exceed the function argument limit.
Returns:

A list of error messages for all possible errors that were found.

def dump(self):
581    def dump(self):
582        """
583        Dump this Expression to a JSON-serializable dict.
584        """
585        from sqlglot.serde import dump
586
587        return dump(self)

Dump this Expression to a JSON-serializable dict.

@classmethod
def load(cls, obj):
589    @classmethod
590    def load(cls, obj):
591        """
592        Load a dict (as returned by `Expression.dump`) into an Expression instance.
593        """
594        from sqlglot.serde import load
595
596        return load(obj)

Load a dict (as returned by Expression.dump) into an Expression instance.

class Condition(Expression):
606class Condition(Expression):
607    def and_(self, *expressions, dialect=None, **opts):
608        """
609        AND this condition with one or multiple expressions.
610
611        Example:
612            >>> condition("x=1").and_("y=1").sql()
613            'x = 1 AND y = 1'
614
615        Args:
616            *expressions (str | Expression): the SQL code strings to parse.
617                If an `Expression` instance is passed, it will be used as-is.
618            dialect (str): the dialect used to parse the input expression.
619            opts (kwargs): other options to use to parse the input expressions.
620
621        Returns:
622            And: the new condition.
623        """
624        return and_(self, *expressions, dialect=dialect, **opts)
625
626    def or_(self, *expressions, dialect=None, **opts):
627        """
628        OR this condition with one or multiple expressions.
629
630        Example:
631            >>> condition("x=1").or_("y=1").sql()
632            'x = 1 OR y = 1'
633
634        Args:
635            *expressions (str | Expression): the SQL code strings to parse.
636                If an `Expression` instance is passed, it will be used as-is.
637            dialect (str): the dialect used to parse the input expression.
638            opts (kwargs): other options to use to parse the input expressions.
639
640        Returns:
641            Or: the new condition.
642        """
643        return or_(self, *expressions, dialect=dialect, **opts)
644
645    def not_(self):
646        """
647        Wrap this condition with NOT.
648
649        Example:
650            >>> condition("x=1").not_().sql()
651            'NOT x = 1'
652
653        Returns:
654            Not: the new condition.
655        """
656        return not_(self)
def and_(self, *expressions, dialect=None, **opts):
607    def and_(self, *expressions, dialect=None, **opts):
608        """
609        AND this condition with one or multiple expressions.
610
611        Example:
612            >>> condition("x=1").and_("y=1").sql()
613            'x = 1 AND y = 1'
614
615        Args:
616            *expressions (str | Expression): the SQL code strings to parse.
617                If an `Expression` instance is passed, it will be used as-is.
618            dialect (str): the dialect used to parse the input expression.
619            opts (kwargs): other options to use to parse the input expressions.
620
621        Returns:
622            And: the new condition.
623        """
624        return and_(self, *expressions, dialect=dialect, **opts)

AND this condition with one or multiple expressions.

Example:
>>> condition("x=1").and_("y=1").sql()
'x = 1 AND y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

And: the new condition.

def or_(self, *expressions, dialect=None, **opts):
626    def or_(self, *expressions, dialect=None, **opts):
627        """
628        OR this condition with one or multiple expressions.
629
630        Example:
631            >>> condition("x=1").or_("y=1").sql()
632            'x = 1 OR y = 1'
633
634        Args:
635            *expressions (str | Expression): the SQL code strings to parse.
636                If an `Expression` instance is passed, it will be used as-is.
637            dialect (str): the dialect used to parse the input expression.
638            opts (kwargs): other options to use to parse the input expressions.
639
640        Returns:
641            Or: the new condition.
642        """
643        return or_(self, *expressions, dialect=dialect, **opts)

OR this condition with one or multiple expressions.

Example:
>>> condition("x=1").or_("y=1").sql()
'x = 1 OR y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Or: the new condition.

def not_(self):
645    def not_(self):
646        """
647        Wrap this condition with NOT.
648
649        Example:
650            >>> condition("x=1").not_().sql()
651            'NOT x = 1'
652
653        Returns:
654            Not: the new condition.
655        """
656        return not_(self)

Wrap this condition with NOT.

Example:
>>> condition("x=1").not_().sql()
'NOT x = 1'
Returns:

Not: the new condition.

class Predicate(Condition):
659class Predicate(Condition):
660    """Relationships like x = y, x > 1, x >= y."""

Relationships like x = y, x > 1, x >= y.

class DerivedTable(Expression):
663class DerivedTable(Expression):
664    @property
665    def alias_column_names(self):
666        table_alias = self.args.get("alias")
667        if not table_alias:
668            return []
669        column_list = table_alias.assert_is(TableAlias).args.get("columns") or []
670        return [c.name for c in column_list]
671
672    @property
673    def selects(self):
674        alias = self.args.get("alias")
675
676        if alias:
677            return alias.columns
678        return []
679
680    @property
681    def named_selects(self):
682        return [select.output_name for select in self.selects]
class Unionable(Expression):
685class Unionable(Expression):
686    def union(self, expression, distinct=True, dialect=None, **opts):
687        """
688        Builds a UNION expression.
689
690        Example:
691            >>> import sqlglot
692            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
693            'SELECT * FROM foo UNION SELECT * FROM bla'
694
695        Args:
696            expression (str | Expression): the SQL code string.
697                If an `Expression` instance is passed, it will be used as-is.
698            distinct (bool): set the DISTINCT flag if and only if this is true.
699            dialect (str): the dialect used to parse the input expression.
700            opts (kwargs): other options to use to parse the input expressions.
701        Returns:
702            Union: the Union expression.
703        """
704        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
705
706    def intersect(self, expression, distinct=True, dialect=None, **opts):
707        """
708        Builds an INTERSECT expression.
709
710        Example:
711            >>> import sqlglot
712            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
713            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
714
715        Args:
716            expression (str | Expression): the SQL code string.
717                If an `Expression` instance is passed, it will be used as-is.
718            distinct (bool): set the DISTINCT flag if and only if this is true.
719            dialect (str): the dialect used to parse the input expression.
720            opts (kwargs): other options to use to parse the input expressions.
721        Returns:
722            Intersect: the Intersect expression
723        """
724        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
725
726    def except_(self, expression, distinct=True, dialect=None, **opts):
727        """
728        Builds an EXCEPT expression.
729
730        Example:
731            >>> import sqlglot
732            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
733            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
734
735        Args:
736            expression (str | Expression): the SQL code string.
737                If an `Expression` instance is passed, it will be used as-is.
738            distinct (bool): set the DISTINCT flag if and only if this is true.
739            dialect (str): the dialect used to parse the input expression.
740            opts (kwargs): other options to use to parse the input expressions.
741        Returns:
742            Except: the Except expression
743        """
744        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
def union(self, expression, distinct=True, dialect=None, **opts):
686    def union(self, expression, distinct=True, dialect=None, **opts):
687        """
688        Builds a UNION expression.
689
690        Example:
691            >>> import sqlglot
692            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
693            'SELECT * FROM foo UNION SELECT * FROM bla'
694
695        Args:
696            expression (str | Expression): the SQL code string.
697                If an `Expression` instance is passed, it will be used as-is.
698            distinct (bool): set the DISTINCT flag if and only if this is true.
699            dialect (str): the dialect used to parse the input expression.
700            opts (kwargs): other options to use to parse the input expressions.
701        Returns:
702            Union: the Union expression.
703        """
704        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds a UNION expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Union: the Union expression.

def intersect(self, expression, distinct=True, dialect=None, **opts):
706    def intersect(self, expression, distinct=True, dialect=None, **opts):
707        """
708        Builds an INTERSECT expression.
709
710        Example:
711            >>> import sqlglot
712            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
713            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
714
715        Args:
716            expression (str | Expression): the SQL code string.
717                If an `Expression` instance is passed, it will be used as-is.
718            distinct (bool): set the DISTINCT flag if and only if this is true.
719            dialect (str): the dialect used to parse the input expression.
720            opts (kwargs): other options to use to parse the input expressions.
721        Returns:
722            Intersect: the Intersect expression
723        """
724        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds an INTERSECT expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Intersect: the Intersect expression

def except_(self, expression, distinct=True, dialect=None, **opts):
726    def except_(self, expression, distinct=True, dialect=None, **opts):
727        """
728        Builds an EXCEPT expression.
729
730        Example:
731            >>> import sqlglot
732            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
733            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
734
735        Args:
736            expression (str | Expression): the SQL code string.
737                If an `Expression` instance is passed, it will be used as-is.
738            distinct (bool): set the DISTINCT flag if and only if this is true.
739            dialect (str): the dialect used to parse the input expression.
740            opts (kwargs): other options to use to parse the input expressions.
741        Returns:
742            Except: the Except expression
743        """
744        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds an EXCEPT expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Except: the Except expression

class UDTF(DerivedTable, Unionable):
747class UDTF(DerivedTable, Unionable):
748    pass
class Cache(Expression):
751class Cache(Expression):
752    arg_types = {
753        "with": False,
754        "this": True,
755        "lazy": False,
756        "options": False,
757        "expression": False,
758    }
class Uncache(Expression):
761class Uncache(Expression):
762    arg_types = {"this": True, "exists": False}
class Create(Expression):
765class Create(Expression):
766    arg_types = {
767        "with": False,
768        "this": True,
769        "kind": True,
770        "expression": False,
771        "set": False,
772        "multiset": False,
773        "global_temporary": False,
774        "volatile": False,
775        "exists": False,
776        "properties": False,
777        "temporary": False,
778        "transient": False,
779        "external": False,
780        "replace": False,
781        "unique": False,
782        "materialized": False,
783        "data": False,
784        "statistics": False,
785        "no_primary_index": False,
786        "indexes": False,
787        "no_schema_binding": False,
788        "begin": False,
789    }
class Describe(Expression):
792class Describe(Expression):
793    arg_types = {"this": True, "kind": False}
class Set(Expression):
796class Set(Expression):
797    arg_types = {"expressions": True}
class SetItem(Expression):
800class SetItem(Expression):
801    arg_types = {
802        "this": False,
803        "expressions": False,
804        "kind": False,
805        "collate": False,  # MySQL SET NAMES statement
806        "global": False,
807    }
class Show(Expression):
810class Show(Expression):
811    arg_types = {
812        "this": True,
813        "target": False,
814        "offset": False,
815        "limit": False,
816        "like": False,
817        "where": False,
818        "db": False,
819        "full": False,
820        "mutex": False,
821        "query": False,
822        "channel": False,
823        "global": False,
824        "log": False,
825        "position": False,
826        "types": False,
827    }
class UserDefinedFunction(Expression):
830class UserDefinedFunction(Expression):
831    arg_types = {"this": True, "expressions": False, "wrapped": False}
class CharacterSet(Expression):
834class CharacterSet(Expression):
835    arg_types = {"this": True, "default": False}
class With(Expression):
838class With(Expression):
839    arg_types = {"expressions": True, "recursive": False}
840
841    @property
842    def recursive(self) -> bool:
843        return bool(self.args.get("recursive"))
class WithinGroup(Expression):
846class WithinGroup(Expression):
847    arg_types = {"this": True, "expression": False}
class CTE(DerivedTable):
850class CTE(DerivedTable):
851    arg_types = {"this": True, "alias": True}
class TableAlias(Expression):
854class TableAlias(Expression):
855    arg_types = {"this": False, "columns": False}
856
857    @property
858    def columns(self):
859        return self.args.get("columns") or []
class BitString(Condition):
862class BitString(Condition):
863    pass
class HexString(Condition):
866class HexString(Condition):
867    pass
class ByteString(Condition):
870class ByteString(Condition):
871    pass
class Column(Condition):
874class Column(Condition):
875    arg_types = {"this": True, "table": False, "db": False, "catalog": False}
876
877    @property
878    def table(self) -> str:
879        return self.text("table")
880
881    @property
882    def db(self) -> str:
883        return self.text("db")
884
885    @property
886    def catalog(self) -> str:
887        return self.text("catalog")
888
889    @property
890    def output_name(self) -> str:
891        return self.name
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class ColumnDef(Expression):
894class ColumnDef(Expression):
895    arg_types = {
896        "this": True,
897        "kind": False,
898        "constraints": False,
899        "exists": False,
900    }
class AlterColumn(Expression):
903class AlterColumn(Expression):
904    arg_types = {
905        "this": True,
906        "dtype": False,
907        "collate": False,
908        "using": False,
909        "default": False,
910        "drop": False,
911    }
class RenameTable(Expression):
914class RenameTable(Expression):
915    pass
class ColumnConstraint(Expression):
918class ColumnConstraint(Expression):
919    arg_types = {"this": False, "kind": True}
class ColumnConstraintKind(Expression):
922class ColumnConstraintKind(Expression):
923    pass
class AutoIncrementColumnConstraint(ColumnConstraintKind):
926class AutoIncrementColumnConstraint(ColumnConstraintKind):
927    pass
class CaseSpecificColumnConstraint(ColumnConstraintKind):
930class CaseSpecificColumnConstraint(ColumnConstraintKind):
931    arg_types = {"not_": True}
class CharacterSetColumnConstraint(ColumnConstraintKind):
934class CharacterSetColumnConstraint(ColumnConstraintKind):
935    arg_types = {"this": True}
class CheckColumnConstraint(ColumnConstraintKind):
938class CheckColumnConstraint(ColumnConstraintKind):
939    pass
class CollateColumnConstraint(ColumnConstraintKind):
942class CollateColumnConstraint(ColumnConstraintKind):
943    pass
class CommentColumnConstraint(ColumnConstraintKind):
946class CommentColumnConstraint(ColumnConstraintKind):
947    pass
class CompressColumnConstraint(ColumnConstraintKind):
950class CompressColumnConstraint(ColumnConstraintKind):
951    pass
class DateFormatColumnConstraint(ColumnConstraintKind):
954class DateFormatColumnConstraint(ColumnConstraintKind):
955    arg_types = {"this": True}
class DefaultColumnConstraint(ColumnConstraintKind):
958class DefaultColumnConstraint(ColumnConstraintKind):
959    pass
class EncodeColumnConstraint(ColumnConstraintKind):
962class EncodeColumnConstraint(ColumnConstraintKind):
963    pass
class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
966class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
967    # this: True -> ALWAYS, this: False -> BY DEFAULT
968    arg_types = {
969        "this": False,
970        "start": False,
971        "increment": False,
972        "minvalue": False,
973        "maxvalue": False,
974        "cycle": False,
975    }
class InlineLengthColumnConstraint(ColumnConstraintKind):
978class InlineLengthColumnConstraint(ColumnConstraintKind):
979    pass
class NotNullColumnConstraint(ColumnConstraintKind):
982class NotNullColumnConstraint(ColumnConstraintKind):
983    arg_types = {"allow_null": False}
class PrimaryKeyColumnConstraint(ColumnConstraintKind):
986class PrimaryKeyColumnConstraint(ColumnConstraintKind):
987    arg_types = {"desc": False}
class TitleColumnConstraint(ColumnConstraintKind):
990class TitleColumnConstraint(ColumnConstraintKind):
991    pass
class UniqueColumnConstraint(ColumnConstraintKind):
994class UniqueColumnConstraint(ColumnConstraintKind):
995    arg_types: t.Dict[str, t.Any] = {}
class UppercaseColumnConstraint(ColumnConstraintKind):
998class UppercaseColumnConstraint(ColumnConstraintKind):
999    arg_types: t.Dict[str, t.Any] = {}
class PathColumnConstraint(ColumnConstraintKind):
1002class PathColumnConstraint(ColumnConstraintKind):
1003    pass
class Constraint(Expression):
1006class Constraint(Expression):
1007    arg_types = {"this": True, "expressions": True}
class Delete(Expression):
1010class Delete(Expression):
1011    arg_types = {"with": False, "this": False, "using": False, "where": False}
class Drop(Expression):
1014class Drop(Expression):
1015    arg_types = {
1016        "this": False,
1017        "kind": False,
1018        "exists": False,
1019        "temporary": False,
1020        "materialized": False,
1021        "cascade": False,
1022    }
class Filter(Expression):
1025class Filter(Expression):
1026    arg_types = {"this": True, "expression": True}
class Check(Expression):
1029class Check(Expression):
1030    pass
class Directory(Expression):
1033class Directory(Expression):
1034    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1035    arg_types = {"this": True, "local": False, "row_format": False}
class ForeignKey(Expression):
1038class ForeignKey(Expression):
1039    arg_types = {
1040        "expressions": True,
1041        "reference": False,
1042        "delete": False,
1043        "update": False,
1044    }
class PrimaryKey(Expression):
1047class PrimaryKey(Expression):
1048    arg_types = {"expressions": True, "options": False}
class Unique(Expression):
1051class Unique(Expression):
1052    arg_types = {"expressions": True}
class Into(Expression):
1057class Into(Expression):
1058    arg_types = {"this": True, "temporary": False, "unlogged": False}
class From(Expression):
1061class From(Expression):
1062    arg_types = {"expressions": True}
class Having(Expression):
1065class Having(Expression):
1066    pass
class Hint(Expression):
1069class Hint(Expression):
1070    arg_types = {"expressions": True}
class JoinHint(Expression):
1073class JoinHint(Expression):
1074    arg_types = {"this": True, "expressions": True}
class Identifier(Expression):
1077class Identifier(Expression):
1078    arg_types = {"this": True, "quoted": False}
1079
1080    @property
1081    def quoted(self):
1082        return bool(self.args.get("quoted"))
1083
1084    def __eq__(self, other):
1085        return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this)
1086
1087    def __hash__(self):
1088        return hash((self.key, self.this.lower()))
1089
1090    @property
1091    def output_name(self):
1092        return self.name
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Index(Expression):
1095class Index(Expression):
1096    arg_types = {
1097        "this": False,
1098        "table": False,
1099        "where": False,
1100        "columns": False,
1101        "unique": False,
1102        "primary": False,
1103        "amp": False,  # teradata
1104    }
class Insert(Expression):
1107class Insert(Expression):
1108    arg_types = {
1109        "with": False,
1110        "this": True,
1111        "expression": False,
1112        "overwrite": False,
1113        "exists": False,
1114        "partition": False,
1115        "alternative": False,
1116    }
class Introducer(Expression):
1120class Introducer(Expression):
1121    arg_types = {"this": True, "expression": True}
class National(Expression):
1125class National(Expression):
1126    pass
class LoadData(Expression):
1129class LoadData(Expression):
1130    arg_types = {
1131        "this": True,
1132        "local": False,
1133        "overwrite": False,
1134        "inpath": True,
1135        "partition": False,
1136        "input_format": False,
1137        "serde": False,
1138    }
class Partition(Expression):
1141class Partition(Expression):
1142    arg_types = {"expressions": True}
class Fetch(Expression):
1145class Fetch(Expression):
1146    arg_types = {"direction": False, "count": False}
class Group(Expression):
1149class Group(Expression):
1150    arg_types = {
1151        "expressions": False,
1152        "grouping_sets": False,
1153        "cube": False,
1154        "rollup": False,
1155    }
class Lambda(Expression):
1158class Lambda(Expression):
1159    arg_types = {"this": True, "expressions": True}
class Limit(Expression):
1162class Limit(Expression):
1163    arg_types = {"this": False, "expression": True}
class Literal(Condition):
1166class Literal(Condition):
1167    arg_types = {"this": True, "is_string": True}
1168
1169    def __eq__(self, other):
1170        return (
1171            isinstance(other, Literal)
1172            and self.this == other.this
1173            and self.args["is_string"] == other.args["is_string"]
1174        )
1175
1176    def __hash__(self):
1177        return hash((self.key, self.this, self.args["is_string"]))
1178
1179    @classmethod
1180    def number(cls, number) -> Literal:
1181        return cls(this=str(number), is_string=False)
1182
1183    @classmethod
1184    def string(cls, string) -> Literal:
1185        return cls(this=str(string), is_string=True)
1186
1187    @property
1188    def output_name(self):
1189        return self.name
@classmethod
def number(cls, number) -> sqlglot.expressions.Literal:
1179    @classmethod
1180    def number(cls, number) -> Literal:
1181        return cls(this=str(number), is_string=False)
@classmethod
def string(cls, string) -> sqlglot.expressions.Literal:
1183    @classmethod
1184    def string(cls, string) -> Literal:
1185        return cls(this=str(string), is_string=True)
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Join(Expression):
1192class Join(Expression):
1193    arg_types = {
1194        "this": True,
1195        "on": False,
1196        "side": False,
1197        "kind": False,
1198        "using": False,
1199        "natural": False,
1200    }
1201
1202    @property
1203    def kind(self):
1204        return self.text("kind").upper()
1205
1206    @property
1207    def side(self):
1208        return self.text("side").upper()
1209
1210    @property
1211    def alias_or_name(self):
1212        return self.this.alias_or_name
1213
1214    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1215        """
1216        Append to or set the ON expressions.
1217
1218        Example:
1219            >>> import sqlglot
1220            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1221            'JOIN x ON y = 1'
1222
1223        Args:
1224            *expressions (str | Expression): the SQL code strings to parse.
1225                If an `Expression` instance is passed, it will be used as-is.
1226                Multiple expressions are combined with an AND operator.
1227            append (bool): if `True`, AND the new expressions to any existing expression.
1228                Otherwise, this resets the expression.
1229            dialect (str): the dialect used to parse the input expressions.
1230            copy (bool): if `False`, modify this expression instance in-place.
1231            opts (kwargs): other options to use to parse the input expressions.
1232
1233        Returns:
1234            Join: the modified join expression.
1235        """
1236        join = _apply_conjunction_builder(
1237            *expressions,
1238            instance=self,
1239            arg="on",
1240            append=append,
1241            dialect=dialect,
1242            copy=copy,
1243            **opts,
1244        )
1245
1246        if join.kind == "CROSS":
1247            join.set("kind", None)
1248
1249        return join
1250
1251    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1252        """
1253        Append to or set the USING expressions.
1254
1255        Example:
1256            >>> import sqlglot
1257            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1258            'JOIN x USING (foo, bla)'
1259
1260        Args:
1261            *expressions (str | Expression): the SQL code strings to parse.
1262                If an `Expression` instance is passed, it will be used as-is.
1263            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1264                Otherwise, this resets the expression.
1265            dialect (str): the dialect used to parse the input expressions.
1266            copy (bool): if `False`, modify this expression instance in-place.
1267            opts (kwargs): other options to use to parse the input expressions.
1268
1269        Returns:
1270            Join: the modified join expression.
1271        """
1272        join = _apply_list_builder(
1273            *expressions,
1274            instance=self,
1275            arg="using",
1276            append=append,
1277            dialect=dialect,
1278            copy=copy,
1279            **opts,
1280        )
1281
1282        if join.kind == "CROSS":
1283            join.set("kind", None)
1284
1285        return join
def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1214    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1215        """
1216        Append to or set the ON expressions.
1217
1218        Example:
1219            >>> import sqlglot
1220            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1221            'JOIN x ON y = 1'
1222
1223        Args:
1224            *expressions (str | Expression): the SQL code strings to parse.
1225                If an `Expression` instance is passed, it will be used as-is.
1226                Multiple expressions are combined with an AND operator.
1227            append (bool): if `True`, AND the new expressions to any existing expression.
1228                Otherwise, this resets the expression.
1229            dialect (str): the dialect used to parse the input expressions.
1230            copy (bool): if `False`, modify this expression instance in-place.
1231            opts (kwargs): other options to use to parse the input expressions.
1232
1233        Returns:
1234            Join: the modified join expression.
1235        """
1236        join = _apply_conjunction_builder(
1237            *expressions,
1238            instance=self,
1239            arg="on",
1240            append=append,
1241            dialect=dialect,
1242            copy=copy,
1243            **opts,
1244        )
1245
1246        if join.kind == "CROSS":
1247            join.set("kind", None)
1248
1249        return join

Append to or set the ON expressions.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
'JOIN x ON y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Join: the modified join expression.

def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1251    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1252        """
1253        Append to or set the USING expressions.
1254
1255        Example:
1256            >>> import sqlglot
1257            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1258            'JOIN x USING (foo, bla)'
1259
1260        Args:
1261            *expressions (str | Expression): the SQL code strings to parse.
1262                If an `Expression` instance is passed, it will be used as-is.
1263            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1264                Otherwise, this resets the expression.
1265            dialect (str): the dialect used to parse the input expressions.
1266            copy (bool): if `False`, modify this expression instance in-place.
1267            opts (kwargs): other options to use to parse the input expressions.
1268
1269        Returns:
1270            Join: the modified join expression.
1271        """
1272        join = _apply_list_builder(
1273            *expressions,
1274            instance=self,
1275            arg="using",
1276            append=append,
1277            dialect=dialect,
1278            copy=copy,
1279            **opts,
1280        )
1281
1282        if join.kind == "CROSS":
1283            join.set("kind", None)
1284
1285        return join

Append to or set the USING expressions.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
'JOIN x USING (foo, bla)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, concatenate the new expressions to the existing "using" list. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Join: the modified join expression.

class Lateral(UDTF):
1288class Lateral(UDTF):
1289    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
class MatchRecognize(Expression):
1292class MatchRecognize(Expression):
1293    arg_types = {
1294        "partition_by": False,
1295        "order": False,
1296        "measures": False,
1297        "rows": False,
1298        "after": False,
1299        "pattern": False,
1300        "define": False,
1301    }
class Final(Expression):
1306class Final(Expression):
1307    pass
class Offset(Expression):
1310class Offset(Expression):
1311    arg_types = {"this": False, "expression": True}
class Order(Expression):
1314class Order(Expression):
1315    arg_types = {"this": False, "expressions": True}
class Cluster(Order):
1320class Cluster(Order):
1321    pass
class Distribute(Order):
1324class Distribute(Order):
1325    pass
class Sort(Order):
1328class Sort(Order):
1329    pass
class Ordered(Expression):
1332class Ordered(Expression):
1333    arg_types = {"this": True, "desc": True, "nulls_first": True}
class Property(Expression):
1336class Property(Expression):
1337    arg_types = {"this": True, "value": True}
class AlgorithmProperty(Property):
1340class AlgorithmProperty(Property):
1341    arg_types = {"this": True}
class DefinerProperty(Property):
1344class DefinerProperty(Property):
1345    arg_types = {"this": True}
class SqlSecurityProperty(Property):
1348class SqlSecurityProperty(Property):
1349    arg_types = {"definer": True}
class TableFormatProperty(Property):
1352class TableFormatProperty(Property):
1353    arg_types = {"this": True}
class PartitionedByProperty(Property):
1356class PartitionedByProperty(Property):
1357    arg_types = {"this": True}
class FileFormatProperty(Property):
1360class FileFormatProperty(Property):
1361    arg_types = {"this": True}
class DistKeyProperty(Property):
1364class DistKeyProperty(Property):
1365    arg_types = {"this": True}
class SortKeyProperty(Property):
1368class SortKeyProperty(Property):
1369    arg_types = {"this": True, "compound": False}
class DistStyleProperty(Property):
1372class DistStyleProperty(Property):
1373    arg_types = {"this": True}
class LikeProperty(Property):
1376class LikeProperty(Property):
1377    arg_types = {"this": True, "expressions": False}
class LocationProperty(Property):
1380class LocationProperty(Property):
1381    arg_types = {"this": True}
class EngineProperty(Property):
1384class EngineProperty(Property):
1385    arg_types = {"this": True}
class AutoIncrementProperty(Property):
1388class AutoIncrementProperty(Property):
1389    arg_types = {"this": True}
class CharacterSetProperty(Property):
1392class CharacterSetProperty(Property):
1393    arg_types = {"this": True, "default": True}
class CollateProperty(Property):
1396class CollateProperty(Property):
1397    arg_types = {"this": True}
class SchemaCommentProperty(Property):
1400class SchemaCommentProperty(Property):
1401    arg_types = {"this": True}
class ReturnsProperty(Property):
1404class ReturnsProperty(Property):
1405    arg_types = {"this": True, "is_table": False, "table": False}
class LanguageProperty(Property):
1408class LanguageProperty(Property):
1409    arg_types = {"this": True}
class ExecuteAsProperty(Property):
1412class ExecuteAsProperty(Property):
1413    arg_types = {"this": True}
class VolatilityProperty(Property):
1416class VolatilityProperty(Property):
1417    arg_types = {"this": True}
class RowFormatDelimitedProperty(Property):
1420class RowFormatDelimitedProperty(Property):
1421    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
1422    arg_types = {
1423        "fields": False,
1424        "escaped": False,
1425        "collection_items": False,
1426        "map_keys": False,
1427        "lines": False,
1428        "null": False,
1429        "serde": False,
1430    }
class RowFormatSerdeProperty(Property):
1433class RowFormatSerdeProperty(Property):
1434    arg_types = {"this": True}
class SerdeProperties(Property):
1437class SerdeProperties(Property):
1438    arg_types = {"expressions": True}
class FallbackProperty(Property):
1441class FallbackProperty(Property):
1442    arg_types = {"no": True, "protection": False}
class WithJournalTableProperty(Property):
1445class WithJournalTableProperty(Property):
1446    arg_types = {"this": True}
class LogProperty(Property):
1449class LogProperty(Property):
1450    arg_types = {"no": True}
class JournalProperty(Property):
1453class JournalProperty(Property):
1454    arg_types = {"no": True, "dual": False, "before": False}
class AfterJournalProperty(Property):
1457class AfterJournalProperty(Property):
1458    arg_types = {"no": True, "dual": False, "local": False}
class ChecksumProperty(Property):
1461class ChecksumProperty(Property):
1462    arg_types = {"on": False, "default": False}
class FreespaceProperty(Property):
1465class FreespaceProperty(Property):
1466    arg_types = {"this": True, "percent": False}
class MergeBlockRatioProperty(Property):
1469class MergeBlockRatioProperty(Property):
1470    arg_types = {"this": False, "no": False, "default": False, "percent": False}
class DataBlocksizeProperty(Property):
1473class DataBlocksizeProperty(Property):
1474    arg_types = {"size": False, "units": False, "min": False, "default": False}
class BlockCompressionProperty(Property):
1477class BlockCompressionProperty(Property):
1478    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
class IsolatedLoadingProperty(Property):
1481class IsolatedLoadingProperty(Property):
1482    arg_types = {
1483        "no": True,
1484        "concurrent": True,
1485        "for_all": True,
1486        "for_insert": True,
1487        "for_none": True,
1488    }
class LockingProperty(Property):
1491class LockingProperty(Property):
1492    arg_types = {
1493        "this": False,
1494        "kind": True,
1495        "for_or_in": True,
1496        "lock_type": True,
1497        "override": False,
1498    }
class Properties(Expression):
1501class Properties(Expression):
1502    arg_types = {"expressions": True}
1503
1504    NAME_TO_PROPERTY = {
1505        "ALGORITHM": AlgorithmProperty,
1506        "AUTO_INCREMENT": AutoIncrementProperty,
1507        "CHARACTER SET": CharacterSetProperty,
1508        "COLLATE": CollateProperty,
1509        "COMMENT": SchemaCommentProperty,
1510        "DEFINER": DefinerProperty,
1511        "DISTKEY": DistKeyProperty,
1512        "DISTSTYLE": DistStyleProperty,
1513        "ENGINE": EngineProperty,
1514        "EXECUTE AS": ExecuteAsProperty,
1515        "FORMAT": FileFormatProperty,
1516        "LANGUAGE": LanguageProperty,
1517        "LOCATION": LocationProperty,
1518        "PARTITIONED_BY": PartitionedByProperty,
1519        "RETURNS": ReturnsProperty,
1520        "SORTKEY": SortKeyProperty,
1521        "TABLE_FORMAT": TableFormatProperty,
1522    }
1523
1524    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
1525
1526    # CREATE property locations
1527    # Form: schema specified
1528    #   create [POST_CREATE]
1529    #     table a [POST_NAME]
1530    #     (b int) [POST_SCHEMA]
1531    #     with ([POST_WITH])
1532    #     index (b) [POST_INDEX]
1533    #
1534    # Form: alias selection
1535    #   create [POST_CREATE]
1536    #     table a [POST_NAME]
1537    #     as [POST_ALIAS] (select * from b)
1538    #     index (c) [POST_INDEX]
1539    class Location(AutoName):
1540        POST_CREATE = auto()
1541        POST_NAME = auto()
1542        POST_SCHEMA = auto()
1543        POST_WITH = auto()
1544        POST_ALIAS = auto()
1545        POST_INDEX = auto()
1546        UNSUPPORTED = auto()
1547
1548    @classmethod
1549    def from_dict(cls, properties_dict) -> Properties:
1550        expressions = []
1551        for key, value in properties_dict.items():
1552            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1553            if property_cls:
1554                expressions.append(property_cls(this=convert(value)))
1555            else:
1556                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1557
1558        return cls(expressions=expressions)
@classmethod
def from_dict(cls, properties_dict) -> sqlglot.expressions.Properties:
1548    @classmethod
1549    def from_dict(cls, properties_dict) -> Properties:
1550        expressions = []
1551        for key, value in properties_dict.items():
1552            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1553            if property_cls:
1554                expressions.append(property_cls(this=convert(value)))
1555            else:
1556                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1557
1558        return cls(expressions=expressions)
class Properties.Location(sqlglot.helper.AutoName):
1539    class Location(AutoName):
1540        POST_CREATE = auto()
1541        POST_NAME = auto()
1542        POST_SCHEMA = auto()
1543        POST_WITH = auto()
1544        POST_ALIAS = auto()
1545        POST_INDEX = auto()
1546        UNSUPPORTED = auto()

An enumeration.

POST_CREATE = <Location.POST_CREATE: 'POST_CREATE'>
POST_NAME = <Location.POST_NAME: 'POST_NAME'>
POST_SCHEMA = <Location.POST_SCHEMA: 'POST_SCHEMA'>
POST_WITH = <Location.POST_WITH: 'POST_WITH'>
POST_ALIAS = <Location.POST_ALIAS: 'POST_ALIAS'>
POST_INDEX = <Location.POST_INDEX: 'POST_INDEX'>
UNSUPPORTED = <Location.UNSUPPORTED: 'UNSUPPORTED'>
Inherited Members
enum.Enum
name
value
class Qualify(Expression):
1561class Qualify(Expression):
1562    pass
class Return(Expression):
1566class Return(Expression):
1567    pass
class Reference(Expression):
1570class Reference(Expression):
1571    arg_types = {"this": True, "expressions": False, "options": False}
class Tuple(Expression):
1574class Tuple(Expression):
1575    arg_types = {"expressions": False}
class Subqueryable(Unionable):
1578class Subqueryable(Unionable):
1579    def subquery(self, alias=None, copy=True) -> Subquery:
1580        """
1581        Convert this expression to an aliased expression that can be used as a Subquery.
1582
1583        Example:
1584            >>> subquery = Select().select("x").from_("tbl").subquery()
1585            >>> Select().select("x").from_(subquery).sql()
1586            'SELECT x FROM (SELECT x FROM tbl)'
1587
1588        Args:
1589            alias (str | Identifier): an optional alias for the subquery
1590            copy (bool): if `False`, modify this expression instance in-place.
1591
1592        Returns:
1593            Alias: the subquery
1594        """
1595        instance = _maybe_copy(self, copy)
1596        return Subquery(
1597            this=instance,
1598            alias=TableAlias(this=to_identifier(alias)),
1599        )
1600
1601    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1602        raise NotImplementedError
1603
1604    @property
1605    def ctes(self):
1606        with_ = self.args.get("with")
1607        if not with_:
1608            return []
1609        return with_.expressions
1610
1611    @property
1612    def selects(self):
1613        raise NotImplementedError("Subqueryable objects must implement `selects`")
1614
1615    @property
1616    def named_selects(self):
1617        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
1618
1619    def with_(
1620        self,
1621        alias,
1622        as_,
1623        recursive=None,
1624        append=True,
1625        dialect=None,
1626        copy=True,
1627        **opts,
1628    ):
1629        """
1630        Append to or set the common table expressions.
1631
1632        Example:
1633            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1634            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1635
1636        Args:
1637            alias (str | Expression): the SQL code string to parse as the table name.
1638                If an `Expression` instance is passed, this is used as-is.
1639            as_ (str | Expression): the SQL code string to parse as the table expression.
1640                If an `Expression` instance is passed, it will be used as-is.
1641            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1642            append (bool): if `True`, add to any existing expressions.
1643                Otherwise, this resets the expressions.
1644            dialect (str): the dialect used to parse the input expression.
1645            copy (bool): if `False`, modify this expression instance in-place.
1646            opts (kwargs): other options to use to parse the input expressions.
1647
1648        Returns:
1649            Select: the modified expression.
1650        """
1651        alias_expression = maybe_parse(
1652            alias,
1653            dialect=dialect,
1654            into=TableAlias,
1655            **opts,
1656        )
1657        as_expression = maybe_parse(
1658            as_,
1659            dialect=dialect,
1660            **opts,
1661        )
1662        cte = CTE(
1663            this=as_expression,
1664            alias=alias_expression,
1665        )
1666        return _apply_child_list_builder(
1667            cte,
1668            instance=self,
1669            arg="with",
1670            append=append,
1671            copy=copy,
1672            into=With,
1673            properties={"recursive": recursive or False},
1674        )
def subquery(self, alias=None, copy=True) -> sqlglot.expressions.Subquery:
1579    def subquery(self, alias=None, copy=True) -> Subquery:
1580        """
1581        Convert this expression to an aliased expression that can be used as a Subquery.
1582
1583        Example:
1584            >>> subquery = Select().select("x").from_("tbl").subquery()
1585            >>> Select().select("x").from_(subquery).sql()
1586            'SELECT x FROM (SELECT x FROM tbl)'
1587
1588        Args:
1589            alias (str | Identifier): an optional alias for the subquery
1590            copy (bool): if `False`, modify this expression instance in-place.
1591
1592        Returns:
1593            Alias: the subquery
1594        """
1595        instance = _maybe_copy(self, copy)
1596        return Subquery(
1597            this=instance,
1598            alias=TableAlias(this=to_identifier(alias)),
1599        )

Convert this expression to an aliased expression that can be used as a Subquery.

Example:
>>> subquery = Select().select("x").from_("tbl").subquery()
>>> Select().select("x").from_(subquery).sql()
'SELECT x FROM (SELECT x FROM tbl)'
Arguments:
  • alias (str | Identifier): an optional alias for the subquery
  • copy (bool): if False, modify this expression instance in-place.
Returns:

Alias: the subquery

def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1601    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1602        raise NotImplementedError
def with_( self, alias, as_, recursive=None, append=True, dialect=None, copy=True, **opts):
1619    def with_(
1620        self,
1621        alias,
1622        as_,
1623        recursive=None,
1624        append=True,
1625        dialect=None,
1626        copy=True,
1627        **opts,
1628    ):
1629        """
1630        Append to or set the common table expressions.
1631
1632        Example:
1633            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1634            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1635
1636        Args:
1637            alias (str | Expression): the SQL code string to parse as the table name.
1638                If an `Expression` instance is passed, this is used as-is.
1639            as_ (str | Expression): the SQL code string to parse as the table expression.
1640                If an `Expression` instance is passed, it will be used as-is.
1641            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1642            append (bool): if `True`, add to any existing expressions.
1643                Otherwise, this resets the expressions.
1644            dialect (str): the dialect used to parse the input expression.
1645            copy (bool): if `False`, modify this expression instance in-place.
1646            opts (kwargs): other options to use to parse the input expressions.
1647
1648        Returns:
1649            Select: the modified expression.
1650        """
1651        alias_expression = maybe_parse(
1652            alias,
1653            dialect=dialect,
1654            into=TableAlias,
1655            **opts,
1656        )
1657        as_expression = maybe_parse(
1658            as_,
1659            dialect=dialect,
1660            **opts,
1661        )
1662        cte = CTE(
1663            this=as_expression,
1664            alias=alias_expression,
1665        )
1666        return _apply_child_list_builder(
1667            cte,
1668            instance=self,
1669            arg="with",
1670            append=append,
1671            copy=copy,
1672            into=With,
1673            properties={"recursive": recursive or False},
1674        )

Append to or set the common table expressions.

Example:
>>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
Arguments:
  • alias (str | Expression): the SQL code string to parse as the table name. If an Expression instance is passed, this is used as-is.
  • as_ (str | Expression): the SQL code string to parse as the table expression. If an Expression instance is passed, it will be used as-is.
  • recursive (bool): set the RECURSIVE part of the expression. Defaults to False.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

class Table(Expression):
1697class Table(Expression):
1698    arg_types = {
1699        "this": True,
1700        "alias": False,
1701        "db": False,
1702        "catalog": False,
1703        "laterals": False,
1704        "joins": False,
1705        "pivots": False,
1706        "hints": False,
1707        "system_time": False,
1708    }
1709
1710    @property
1711    def db(self) -> str:
1712        return self.text("db")
1713
1714    @property
1715    def catalog(self) -> str:
1716        return self.text("catalog")
class SystemTime(Expression):
1720class SystemTime(Expression):
1721    arg_types = {
1722        "this": False,
1723        "expression": False,
1724        "kind": True,
1725    }
class Union(Subqueryable):
1728class Union(Subqueryable):
1729    arg_types = {
1730        "with": False,
1731        "this": True,
1732        "expression": True,
1733        "distinct": False,
1734        **QUERY_MODIFIERS,
1735    }
1736
1737    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1738        """
1739        Set the LIMIT expression.
1740
1741        Example:
1742            >>> select("1").union(select("1")).limit(1).sql()
1743            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1744
1745        Args:
1746            expression (str | int | Expression): the SQL code string to parse.
1747                This can also be an integer.
1748                If a `Limit` instance is passed, this is used as-is.
1749                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1750            dialect (str): the dialect used to parse the input expression.
1751            copy (bool): if `False`, modify this expression instance in-place.
1752            opts (kwargs): other options to use to parse the input expressions.
1753
1754        Returns:
1755            Select: The limited subqueryable.
1756        """
1757        return (
1758            select("*")
1759            .from_(self.subquery(alias="_l_0", copy=copy))
1760            .limit(expression, dialect=dialect, copy=False, **opts)
1761        )
1762
1763    def select(
1764        self,
1765        *expressions: str | Expression,
1766        append: bool = True,
1767        dialect: DialectType = None,
1768        copy: bool = True,
1769        **opts,
1770    ) -> Union:
1771        """Append to or set the SELECT of the union recursively.
1772
1773        Example:
1774            >>> from sqlglot import parse_one
1775            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1776            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1777
1778        Args:
1779            *expressions: the SQL code strings to parse.
1780                If an `Expression` instance is passed, it will be used as-is.
1781            append: if `True`, add to any existing expressions.
1782                Otherwise, this resets the expressions.
1783            dialect: the dialect used to parse the input expressions.
1784            copy: if `False`, modify this expression instance in-place.
1785            opts: other options to use to parse the input expressions.
1786
1787        Returns:
1788            Union: the modified expression.
1789        """
1790        this = self.copy() if copy else self
1791        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1792        this.expression.unnest().select(
1793            *expressions, append=append, dialect=dialect, copy=False, **opts
1794        )
1795        return this
1796
1797    @property
1798    def named_selects(self):
1799        return self.this.unnest().named_selects
1800
1801    @property
1802    def selects(self):
1803        return self.this.unnest().selects
1804
1805    @property
1806    def left(self):
1807        return self.this
1808
1809    @property
1810    def right(self):
1811        return self.expression
def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1737    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1738        """
1739        Set the LIMIT expression.
1740
1741        Example:
1742            >>> select("1").union(select("1")).limit(1).sql()
1743            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1744
1745        Args:
1746            expression (str | int | Expression): the SQL code string to parse.
1747                This can also be an integer.
1748                If a `Limit` instance is passed, this is used as-is.
1749                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1750            dialect (str): the dialect used to parse the input expression.
1751            copy (bool): if `False`, modify this expression instance in-place.
1752            opts (kwargs): other options to use to parse the input expressions.
1753
1754        Returns:
1755            Select: The limited subqueryable.
1756        """
1757        return (
1758            select("*")
1759            .from_(self.subquery(alias="_l_0", copy=copy))
1760            .limit(expression, dialect=dialect, copy=False, **opts)
1761        )

Set the LIMIT expression.

Example:
>>> select("1").union(select("1")).limit(1).sql()
'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Limit instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Limit.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: The limited subqueryable.

def select( self, *expressions: str | sqlglot.expressions.Expression, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> sqlglot.expressions.Union:
1763    def select(
1764        self,
1765        *expressions: str | Expression,
1766        append: bool = True,
1767        dialect: DialectType = None,
1768        copy: bool = True,
1769        **opts,
1770    ) -> Union:
1771        """Append to or set the SELECT of the union recursively.
1772
1773        Example:
1774            >>> from sqlglot import parse_one
1775            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1776            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1777
1778        Args:
1779            *expressions: the SQL code strings to parse.
1780                If an `Expression` instance is passed, it will be used as-is.
1781            append: if `True`, add to any existing expressions.
1782                Otherwise, this resets the expressions.
1783            dialect: the dialect used to parse the input expressions.
1784            copy: if `False`, modify this expression instance in-place.
1785            opts: other options to use to parse the input expressions.
1786
1787        Returns:
1788            Union: the modified expression.
1789        """
1790        this = self.copy() if copy else self
1791        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1792        this.expression.unnest().select(
1793            *expressions, append=append, dialect=dialect, copy=False, **opts
1794        )
1795        return this

Append to or set the SELECT of the union recursively.

Example:
>>> from sqlglot import parse_one
>>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Union: the modified expression.

class Except(Union):
1814class Except(Union):
1815    pass
class Intersect(Union):
1818class Intersect(Union):
1819    pass
class Unnest(UDTF):
1822class Unnest(UDTF):
1823    arg_types = {
1824        "expressions": True,
1825        "ordinality": False,
1826        "alias": False,
1827        "offset": False,
1828    }
class Update(Expression):
1831class Update(Expression):
1832    arg_types = {
1833        "with": False,
1834        "this": False,
1835        "expressions": True,
1836        "from": False,
1837        "where": False,
1838    }
class Values(UDTF):
1841class Values(UDTF):
1842    arg_types = {
1843        "expressions": True,
1844        "ordinality": False,
1845        "alias": False,
1846    }
class Var(Expression):
1849class Var(Expression):
1850    pass
class Schema(Expression):
1853class Schema(Expression):
1854    arg_types = {"this": False, "expressions": False}
class Lock(Expression):
1859class Lock(Expression):
1860    arg_types = {"update": True}
class Select(Subqueryable):
1863class Select(Subqueryable):
1864    arg_types = {
1865        "with": False,
1866        "expressions": False,
1867        "hint": False,
1868        "distinct": False,
1869        "into": False,
1870        "from": False,
1871        **QUERY_MODIFIERS,
1872    }
1873
1874    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1875        """
1876        Set the FROM expression.
1877
1878        Example:
1879            >>> Select().from_("tbl").select("x").sql()
1880            'SELECT x FROM tbl'
1881
1882        Args:
1883            *expressions (str | Expression): the SQL code strings to parse.
1884                If a `From` instance is passed, this is used as-is.
1885                If another `Expression` instance is passed, it will be wrapped in a `From`.
1886            append (bool): if `True`, add to any existing expressions.
1887                Otherwise, this flattens all the `From` expression into a single expression.
1888            dialect (str): the dialect used to parse the input expression.
1889            copy (bool): if `False`, modify this expression instance in-place.
1890            opts (kwargs): other options to use to parse the input expressions.
1891
1892        Returns:
1893            Select: the modified expression.
1894        """
1895        return _apply_child_list_builder(
1896            *expressions,
1897            instance=self,
1898            arg="from",
1899            append=append,
1900            copy=copy,
1901            prefix="FROM",
1902            into=From,
1903            dialect=dialect,
1904            **opts,
1905        )
1906
1907    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1908        """
1909        Set the GROUP BY expression.
1910
1911        Example:
1912            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1913            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1914
1915        Args:
1916            *expressions (str | Expression): the SQL code strings to parse.
1917                If a `Group` instance is passed, this is used as-is.
1918                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1919                If nothing is passed in then a group by is not applied to the expression
1920            append (bool): if `True`, add to any existing expressions.
1921                Otherwise, this flattens all the `Group` expression into a single expression.
1922            dialect (str): the dialect used to parse the input expression.
1923            copy (bool): if `False`, modify this expression instance in-place.
1924            opts (kwargs): other options to use to parse the input expressions.
1925
1926        Returns:
1927            Select: the modified expression.
1928        """
1929        if not expressions:
1930            return self if not copy else self.copy()
1931        return _apply_child_list_builder(
1932            *expressions,
1933            instance=self,
1934            arg="group",
1935            append=append,
1936            copy=copy,
1937            prefix="GROUP BY",
1938            into=Group,
1939            dialect=dialect,
1940            **opts,
1941        )
1942
1943    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1944        """
1945        Set the ORDER BY expression.
1946
1947        Example:
1948            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
1949            'SELECT x FROM tbl ORDER BY x DESC'
1950
1951        Args:
1952            *expressions (str | Expression): the SQL code strings to parse.
1953                If a `Group` instance is passed, this is used as-is.
1954                If another `Expression` instance is passed, it will be wrapped in a `Order`.
1955            append (bool): if `True`, add to any existing expressions.
1956                Otherwise, this flattens all the `Order` expression into a single expression.
1957            dialect (str): the dialect used to parse the input expression.
1958            copy (bool): if `False`, modify this expression instance in-place.
1959            opts (kwargs): other options to use to parse the input expressions.
1960
1961        Returns:
1962            Select: the modified expression.
1963        """
1964        return _apply_child_list_builder(
1965            *expressions,
1966            instance=self,
1967            arg="order",
1968            append=append,
1969            copy=copy,
1970            prefix="ORDER BY",
1971            into=Order,
1972            dialect=dialect,
1973            **opts,
1974        )
1975
1976    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1977        """
1978        Set the SORT BY expression.
1979
1980        Example:
1981            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
1982            'SELECT x FROM tbl SORT BY x DESC'
1983
1984        Args:
1985            *expressions (str | Expression): the SQL code strings to parse.
1986                If a `Group` instance is passed, this is used as-is.
1987                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
1988            append (bool): if `True`, add to any existing expressions.
1989                Otherwise, this flattens all the `Order` expression into a single expression.
1990            dialect (str): the dialect used to parse the input expression.
1991            copy (bool): if `False`, modify this expression instance in-place.
1992            opts (kwargs): other options to use to parse the input expressions.
1993
1994        Returns:
1995            Select: the modified expression.
1996        """
1997        return _apply_child_list_builder(
1998            *expressions,
1999            instance=self,
2000            arg="sort",
2001            append=append,
2002            copy=copy,
2003            prefix="SORT BY",
2004            into=Sort,
2005            dialect=dialect,
2006            **opts,
2007        )
2008
2009    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2010        """
2011        Set the CLUSTER BY expression.
2012
2013        Example:
2014            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2015            'SELECT x FROM tbl CLUSTER BY x DESC'
2016
2017        Args:
2018            *expressions (str | Expression): the SQL code strings to parse.
2019                If a `Group` instance is passed, this is used as-is.
2020                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2021            append (bool): if `True`, add to any existing expressions.
2022                Otherwise, this flattens all the `Order` expression into a single expression.
2023            dialect (str): the dialect used to parse the input expression.
2024            copy (bool): if `False`, modify this expression instance in-place.
2025            opts (kwargs): other options to use to parse the input expressions.
2026
2027        Returns:
2028            Select: the modified expression.
2029        """
2030        return _apply_child_list_builder(
2031            *expressions,
2032            instance=self,
2033            arg="cluster",
2034            append=append,
2035            copy=copy,
2036            prefix="CLUSTER BY",
2037            into=Cluster,
2038            dialect=dialect,
2039            **opts,
2040        )
2041
2042    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2043        """
2044        Set the LIMIT expression.
2045
2046        Example:
2047            >>> Select().from_("tbl").select("x").limit(10).sql()
2048            'SELECT x FROM tbl LIMIT 10'
2049
2050        Args:
2051            expression (str | int | Expression): the SQL code string to parse.
2052                This can also be an integer.
2053                If a `Limit` instance is passed, this is used as-is.
2054                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2055            dialect (str): the dialect used to parse the input expression.
2056            copy (bool): if `False`, modify this expression instance in-place.
2057            opts (kwargs): other options to use to parse the input expressions.
2058
2059        Returns:
2060            Select: the modified expression.
2061        """
2062        return _apply_builder(
2063            expression=expression,
2064            instance=self,
2065            arg="limit",
2066            into=Limit,
2067            prefix="LIMIT",
2068            dialect=dialect,
2069            copy=copy,
2070            **opts,
2071        )
2072
2073    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2074        """
2075        Set the OFFSET expression.
2076
2077        Example:
2078            >>> Select().from_("tbl").select("x").offset(10).sql()
2079            'SELECT x FROM tbl OFFSET 10'
2080
2081        Args:
2082            expression (str | int | Expression): the SQL code string to parse.
2083                This can also be an integer.
2084                If a `Offset` instance is passed, this is used as-is.
2085                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2086            dialect (str): the dialect used to parse the input expression.
2087            copy (bool): if `False`, modify this expression instance in-place.
2088            opts (kwargs): other options to use to parse the input expressions.
2089
2090        Returns:
2091            Select: the modified expression.
2092        """
2093        return _apply_builder(
2094            expression=expression,
2095            instance=self,
2096            arg="offset",
2097            into=Offset,
2098            prefix="OFFSET",
2099            dialect=dialect,
2100            copy=copy,
2101            **opts,
2102        )
2103
2104    def select(
2105        self,
2106        *expressions: str | Expression,
2107        append: bool = True,
2108        dialect: DialectType = None,
2109        copy: bool = True,
2110        **opts,
2111    ) -> Select:
2112        """
2113        Append to or set the SELECT expressions.
2114
2115        Example:
2116            >>> Select().select("x", "y").sql()
2117            'SELECT x, y'
2118
2119        Args:
2120            *expressions: the SQL code strings to parse.
2121                If an `Expression` instance is passed, it will be used as-is.
2122            append: if `True`, add to any existing expressions.
2123                Otherwise, this resets the expressions.
2124            dialect: the dialect used to parse the input expressions.
2125            copy: if `False`, modify this expression instance in-place.
2126            opts: other options to use to parse the input expressions.
2127
2128        Returns:
2129            Select: the modified expression.
2130        """
2131        return _apply_list_builder(
2132            *expressions,
2133            instance=self,
2134            arg="expressions",
2135            append=append,
2136            dialect=dialect,
2137            copy=copy,
2138            **opts,
2139        )
2140
2141    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2142        """
2143        Append to or set the LATERAL expressions.
2144
2145        Example:
2146            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2147            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2148
2149        Args:
2150            *expressions (str | Expression): the SQL code strings to parse.
2151                If an `Expression` instance is passed, it will be used as-is.
2152            append (bool): if `True`, add to any existing expressions.
2153                Otherwise, this resets the expressions.
2154            dialect (str): the dialect used to parse the input expressions.
2155            copy (bool): if `False`, modify this expression instance in-place.
2156            opts (kwargs): other options to use to parse the input expressions.
2157
2158        Returns:
2159            Select: the modified expression.
2160        """
2161        return _apply_list_builder(
2162            *expressions,
2163            instance=self,
2164            arg="laterals",
2165            append=append,
2166            into=Lateral,
2167            prefix="LATERAL VIEW",
2168            dialect=dialect,
2169            copy=copy,
2170            **opts,
2171        )
2172
2173    def join(
2174        self,
2175        expression,
2176        on=None,
2177        using=None,
2178        append=True,
2179        join_type=None,
2180        join_alias=None,
2181        dialect=None,
2182        copy=True,
2183        **opts,
2184    ) -> Select:
2185        """
2186        Append to or set the JOIN expressions.
2187
2188        Example:
2189            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2190            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2191
2192            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2193            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2194
2195            Use `join_type` to change the type of join:
2196
2197            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2198            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2199
2200        Args:
2201            expression (str | Expression): the SQL code string to parse.
2202                If an `Expression` instance is passed, it will be used as-is.
2203            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2204                If an `Expression` instance is passed, it will be used as-is.
2205            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2206                If an `Expression` instance is passed, it will be used as-is.
2207            append (bool): if `True`, add to any existing expressions.
2208                Otherwise, this resets the expressions.
2209            join_type (str): If set, alter the parsed join type
2210            dialect (str): the dialect used to parse the input expressions.
2211            copy (bool): if `False`, modify this expression instance in-place.
2212            opts (kwargs): other options to use to parse the input expressions.
2213
2214        Returns:
2215            Select: the modified expression.
2216        """
2217        parse_args = {"dialect": dialect, **opts}
2218
2219        try:
2220            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2221        except ParseError:
2222            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2223
2224        join = expression if isinstance(expression, Join) else Join(this=expression)
2225
2226        if isinstance(join.this, Select):
2227            join.this.replace(join.this.subquery())
2228
2229        if join_type:
2230            natural: t.Optional[Token]
2231            side: t.Optional[Token]
2232            kind: t.Optional[Token]
2233
2234            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2235
2236            if natural:
2237                join.set("natural", True)
2238            if side:
2239                join.set("side", side.text)
2240            if kind:
2241                join.set("kind", kind.text)
2242
2243        if on:
2244            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2245            join.set("on", on)
2246
2247        if using:
2248            join = _apply_list_builder(
2249                *ensure_collection(using),
2250                instance=join,
2251                arg="using",
2252                append=append,
2253                copy=copy,
2254                **opts,
2255            )
2256
2257        if join_alias:
2258            join.set("this", alias_(join.this, join_alias, table=True))
2259        return _apply_list_builder(
2260            join,
2261            instance=self,
2262            arg="joins",
2263            append=append,
2264            copy=copy,
2265            **opts,
2266        )
2267
2268    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2269        """
2270        Append to or set the WHERE expressions.
2271
2272        Example:
2273            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2274            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2275
2276        Args:
2277            *expressions (str | Expression): the SQL code strings to parse.
2278                If an `Expression` instance is passed, it will be used as-is.
2279                Multiple expressions are combined with an AND operator.
2280            append (bool): if `True`, AND the new expressions to any existing expression.
2281                Otherwise, this resets the expression.
2282            dialect (str): the dialect used to parse the input expressions.
2283            copy (bool): if `False`, modify this expression instance in-place.
2284            opts (kwargs): other options to use to parse the input expressions.
2285
2286        Returns:
2287            Select: the modified expression.
2288        """
2289        return _apply_conjunction_builder(
2290            *expressions,
2291            instance=self,
2292            arg="where",
2293            append=append,
2294            into=Where,
2295            dialect=dialect,
2296            copy=copy,
2297            **opts,
2298        )
2299
2300    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2301        """
2302        Append to or set the HAVING expressions.
2303
2304        Example:
2305            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2306            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2307
2308        Args:
2309            *expressions (str | Expression): the SQL code strings to parse.
2310                If an `Expression` instance is passed, it will be used as-is.
2311                Multiple expressions are combined with an AND operator.
2312            append (bool): if `True`, AND the new expressions to any existing expression.
2313                Otherwise, this resets the expression.
2314            dialect (str): the dialect used to parse the input expressions.
2315            copy (bool): if `False`, modify this expression instance in-place.
2316            opts (kwargs): other options to use to parse the input expressions.
2317
2318        Returns:
2319            Select: the modified expression.
2320        """
2321        return _apply_conjunction_builder(
2322            *expressions,
2323            instance=self,
2324            arg="having",
2325            append=append,
2326            into=Having,
2327            dialect=dialect,
2328            copy=copy,
2329            **opts,
2330        )
2331
2332    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2333        return _apply_list_builder(
2334            *expressions,
2335            instance=self,
2336            arg="windows",
2337            append=append,
2338            into=Window,
2339            dialect=dialect,
2340            copy=copy,
2341            **opts,
2342        )
2343
2344    def distinct(self, distinct=True, copy=True) -> Select:
2345        """
2346        Set the OFFSET expression.
2347
2348        Example:
2349            >>> Select().from_("tbl").select("x").distinct().sql()
2350            'SELECT DISTINCT x FROM tbl'
2351
2352        Args:
2353            distinct (bool): whether the Select should be distinct
2354            copy (bool): if `False`, modify this expression instance in-place.
2355
2356        Returns:
2357            Select: the modified expression.
2358        """
2359        instance = _maybe_copy(self, copy)
2360        instance.set("distinct", Distinct() if distinct else None)
2361        return instance
2362
2363    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2364        """
2365        Convert this expression to a CREATE TABLE AS statement.
2366
2367        Example:
2368            >>> Select().select("*").from_("tbl").ctas("x").sql()
2369            'CREATE TABLE x AS SELECT * FROM tbl'
2370
2371        Args:
2372            table (str | Expression): the SQL code string to parse as the table name.
2373                If another `Expression` instance is passed, it will be used as-is.
2374            properties (dict): an optional mapping of table properties
2375            dialect (str): the dialect used to parse the input table.
2376            copy (bool): if `False`, modify this expression instance in-place.
2377            opts (kwargs): other options to use to parse the input table.
2378
2379        Returns:
2380            Create: the CREATE TABLE AS expression
2381        """
2382        instance = _maybe_copy(self, copy)
2383        table_expression = maybe_parse(
2384            table,
2385            into=Table,
2386            dialect=dialect,
2387            **opts,
2388        )
2389        properties_expression = None
2390        if properties:
2391            properties_expression = Properties.from_dict(properties)
2392
2393        return Create(
2394            this=table_expression,
2395            kind="table",
2396            expression=instance,
2397            properties=properties_expression,
2398        )
2399
2400    def lock(self, update: bool = True, copy: bool = True) -> Select:
2401        """
2402        Set the locking read mode for this expression.
2403
2404        Examples:
2405            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2406            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2407
2408            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2409            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2410
2411        Args:
2412            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2413            copy: if `False`, modify this expression instance in-place.
2414
2415        Returns:
2416            The modified expression.
2417        """
2418
2419        inst = _maybe_copy(self, copy)
2420        inst.set("lock", Lock(update=update))
2421
2422        return inst
2423
2424    @property
2425    def named_selects(self) -> t.List[str]:
2426        return [e.output_name for e in self.expressions if e.alias_or_name]
2427
2428    @property
2429    def selects(self) -> t.List[Expression]:
2430        return self.expressions
def from_( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1874    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1875        """
1876        Set the FROM expression.
1877
1878        Example:
1879            >>> Select().from_("tbl").select("x").sql()
1880            'SELECT x FROM tbl'
1881
1882        Args:
1883            *expressions (str | Expression): the SQL code strings to parse.
1884                If a `From` instance is passed, this is used as-is.
1885                If another `Expression` instance is passed, it will be wrapped in a `From`.
1886            append (bool): if `True`, add to any existing expressions.
1887                Otherwise, this flattens all the `From` expression into a single expression.
1888            dialect (str): the dialect used to parse the input expression.
1889            copy (bool): if `False`, modify this expression instance in-place.
1890            opts (kwargs): other options to use to parse the input expressions.
1891
1892        Returns:
1893            Select: the modified expression.
1894        """
1895        return _apply_child_list_builder(
1896            *expressions,
1897            instance=self,
1898            arg="from",
1899            append=append,
1900            copy=copy,
1901            prefix="FROM",
1902            into=From,
1903            dialect=dialect,
1904            **opts,
1905        )

Set the FROM expression.

Example:
>>> Select().from_("tbl").select("x").sql()
'SELECT x FROM tbl'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a From instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a From.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the From expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def group_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1907    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1908        """
1909        Set the GROUP BY expression.
1910
1911        Example:
1912            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1913            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1914
1915        Args:
1916            *expressions (str | Expression): the SQL code strings to parse.
1917                If a `Group` instance is passed, this is used as-is.
1918                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1919                If nothing is passed in then a group by is not applied to the expression
1920            append (bool): if `True`, add to any existing expressions.
1921                Otherwise, this flattens all the `Group` expression into a single expression.
1922            dialect (str): the dialect used to parse the input expression.
1923            copy (bool): if `False`, modify this expression instance in-place.
1924            opts (kwargs): other options to use to parse the input expressions.
1925
1926        Returns:
1927            Select: the modified expression.
1928        """
1929        if not expressions:
1930            return self if not copy else self.copy()
1931        return _apply_child_list_builder(
1932            *expressions,
1933            instance=self,
1934            arg="group",
1935            append=append,
1936            copy=copy,
1937            prefix="GROUP BY",
1938            into=Group,
1939            dialect=dialect,
1940            **opts,
1941        )

Set the GROUP BY expression.

Example:
>>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
'SELECT x, COUNT(1) FROM tbl GROUP BY x'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Group. If nothing is passed in then a group by is not applied to the expression
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Group expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def order_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1943    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1944        """
1945        Set the ORDER BY expression.
1946
1947        Example:
1948            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
1949            'SELECT x FROM tbl ORDER BY x DESC'
1950
1951        Args:
1952            *expressions (str | Expression): the SQL code strings to parse.
1953                If a `Group` instance is passed, this is used as-is.
1954                If another `Expression` instance is passed, it will be wrapped in a `Order`.
1955            append (bool): if `True`, add to any existing expressions.
1956                Otherwise, this flattens all the `Order` expression into a single expression.
1957            dialect (str): the dialect used to parse the input expression.
1958            copy (bool): if `False`, modify this expression instance in-place.
1959            opts (kwargs): other options to use to parse the input expressions.
1960
1961        Returns:
1962            Select: the modified expression.
1963        """
1964        return _apply_child_list_builder(
1965            *expressions,
1966            instance=self,
1967            arg="order",
1968            append=append,
1969            copy=copy,
1970            prefix="ORDER BY",
1971            into=Order,
1972            dialect=dialect,
1973            **opts,
1974        )

Set the ORDER BY expression.

Example:
>>> Select().from_("tbl").select("x").order_by("x DESC").sql()
'SELECT x FROM tbl ORDER BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Order.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def sort_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1976    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1977        """
1978        Set the SORT BY expression.
1979
1980        Example:
1981            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
1982            'SELECT x FROM tbl SORT BY x DESC'
1983
1984        Args:
1985            *expressions (str | Expression): the SQL code strings to parse.
1986                If a `Group` instance is passed, this is used as-is.
1987                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
1988            append (bool): if `True`, add to any existing expressions.
1989                Otherwise, this flattens all the `Order` expression into a single expression.
1990            dialect (str): the dialect used to parse the input expression.
1991            copy (bool): if `False`, modify this expression instance in-place.
1992            opts (kwargs): other options to use to parse the input expressions.
1993
1994        Returns:
1995            Select: the modified expression.
1996        """
1997        return _apply_child_list_builder(
1998            *expressions,
1999            instance=self,
2000            arg="sort",
2001            append=append,
2002            copy=copy,
2003            prefix="SORT BY",
2004            into=Sort,
2005            dialect=dialect,
2006            **opts,
2007        )

Set the SORT BY expression.

Example:
>>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
'SELECT x FROM tbl SORT BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a SORT.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def cluster_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2009    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2010        """
2011        Set the CLUSTER BY expression.
2012
2013        Example:
2014            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2015            'SELECT x FROM tbl CLUSTER BY x DESC'
2016
2017        Args:
2018            *expressions (str | Expression): the SQL code strings to parse.
2019                If a `Group` instance is passed, this is used as-is.
2020                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2021            append (bool): if `True`, add to any existing expressions.
2022                Otherwise, this flattens all the `Order` expression into a single expression.
2023            dialect (str): the dialect used to parse the input expression.
2024            copy (bool): if `False`, modify this expression instance in-place.
2025            opts (kwargs): other options to use to parse the input expressions.
2026
2027        Returns:
2028            Select: the modified expression.
2029        """
2030        return _apply_child_list_builder(
2031            *expressions,
2032            instance=self,
2033            arg="cluster",
2034            append=append,
2035            copy=copy,
2036            prefix="CLUSTER BY",
2037            into=Cluster,
2038            dialect=dialect,
2039            **opts,
2040        )

Set the CLUSTER BY expression.

Example:
>>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
'SELECT x FROM tbl CLUSTER BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Cluster.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2042    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2043        """
2044        Set the LIMIT expression.
2045
2046        Example:
2047            >>> Select().from_("tbl").select("x").limit(10).sql()
2048            'SELECT x FROM tbl LIMIT 10'
2049
2050        Args:
2051            expression (str | int | Expression): the SQL code string to parse.
2052                This can also be an integer.
2053                If a `Limit` instance is passed, this is used as-is.
2054                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2055            dialect (str): the dialect used to parse the input expression.
2056            copy (bool): if `False`, modify this expression instance in-place.
2057            opts (kwargs): other options to use to parse the input expressions.
2058
2059        Returns:
2060            Select: the modified expression.
2061        """
2062        return _apply_builder(
2063            expression=expression,
2064            instance=self,
2065            arg="limit",
2066            into=Limit,
2067            prefix="LIMIT",
2068            dialect=dialect,
2069            copy=copy,
2070            **opts,
2071        )

Set the LIMIT expression.

Example:
>>> Select().from_("tbl").select("x").limit(10).sql()
'SELECT x FROM tbl LIMIT 10'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Limit instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Limit.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def offset( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2073    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2074        """
2075        Set the OFFSET expression.
2076
2077        Example:
2078            >>> Select().from_("tbl").select("x").offset(10).sql()
2079            'SELECT x FROM tbl OFFSET 10'
2080
2081        Args:
2082            expression (str | int | Expression): the SQL code string to parse.
2083                This can also be an integer.
2084                If a `Offset` instance is passed, this is used as-is.
2085                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2086            dialect (str): the dialect used to parse the input expression.
2087            copy (bool): if `False`, modify this expression instance in-place.
2088            opts (kwargs): other options to use to parse the input expressions.
2089
2090        Returns:
2091            Select: the modified expression.
2092        """
2093        return _apply_builder(
2094            expression=expression,
2095            instance=self,
2096            arg="offset",
2097            into=Offset,
2098            prefix="OFFSET",
2099            dialect=dialect,
2100            copy=copy,
2101            **opts,
2102        )

Set the OFFSET expression.

Example:
>>> Select().from_("tbl").select("x").offset(10).sql()
'SELECT x FROM tbl OFFSET 10'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Offset instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Offset.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def select( self, *expressions: str | sqlglot.expressions.Expression, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> sqlglot.expressions.Select:
2104    def select(
2105        self,
2106        *expressions: str | Expression,
2107        append: bool = True,
2108        dialect: DialectType = None,
2109        copy: bool = True,
2110        **opts,
2111    ) -> Select:
2112        """
2113        Append to or set the SELECT expressions.
2114
2115        Example:
2116            >>> Select().select("x", "y").sql()
2117            'SELECT x, y'
2118
2119        Args:
2120            *expressions: the SQL code strings to parse.
2121                If an `Expression` instance is passed, it will be used as-is.
2122            append: if `True`, add to any existing expressions.
2123                Otherwise, this resets the expressions.
2124            dialect: the dialect used to parse the input expressions.
2125            copy: if `False`, modify this expression instance in-place.
2126            opts: other options to use to parse the input expressions.
2127
2128        Returns:
2129            Select: the modified expression.
2130        """
2131        return _apply_list_builder(
2132            *expressions,
2133            instance=self,
2134            arg="expressions",
2135            append=append,
2136            dialect=dialect,
2137            copy=copy,
2138            **opts,
2139        )

Append to or set the SELECT expressions.

Example:
>>> Select().select("x", "y").sql()
'SELECT x, y'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def lateral( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2141    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2142        """
2143        Append to or set the LATERAL expressions.
2144
2145        Example:
2146            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2147            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2148
2149        Args:
2150            *expressions (str | Expression): the SQL code strings to parse.
2151                If an `Expression` instance is passed, it will be used as-is.
2152            append (bool): if `True`, add to any existing expressions.
2153                Otherwise, this resets the expressions.
2154            dialect (str): the dialect used to parse the input expressions.
2155            copy (bool): if `False`, modify this expression instance in-place.
2156            opts (kwargs): other options to use to parse the input expressions.
2157
2158        Returns:
2159            Select: the modified expression.
2160        """
2161        return _apply_list_builder(
2162            *expressions,
2163            instance=self,
2164            arg="laterals",
2165            append=append,
2166            into=Lateral,
2167            prefix="LATERAL VIEW",
2168            dialect=dialect,
2169            copy=copy,
2170            **opts,
2171        )

Append to or set the LATERAL expressions.

Example:
>>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def join( self, expression, on=None, using=None, append=True, join_type=None, join_alias=None, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2173    def join(
2174        self,
2175        expression,
2176        on=None,
2177        using=None,
2178        append=True,
2179        join_type=None,
2180        join_alias=None,
2181        dialect=None,
2182        copy=True,
2183        **opts,
2184    ) -> Select:
2185        """
2186        Append to or set the JOIN expressions.
2187
2188        Example:
2189            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2190            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2191
2192            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2193            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2194
2195            Use `join_type` to change the type of join:
2196
2197            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2198            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2199
2200        Args:
2201            expression (str | Expression): the SQL code string to parse.
2202                If an `Expression` instance is passed, it will be used as-is.
2203            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2204                If an `Expression` instance is passed, it will be used as-is.
2205            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2206                If an `Expression` instance is passed, it will be used as-is.
2207            append (bool): if `True`, add to any existing expressions.
2208                Otherwise, this resets the expressions.
2209            join_type (str): If set, alter the parsed join type
2210            dialect (str): the dialect used to parse the input expressions.
2211            copy (bool): if `False`, modify this expression instance in-place.
2212            opts (kwargs): other options to use to parse the input expressions.
2213
2214        Returns:
2215            Select: the modified expression.
2216        """
2217        parse_args = {"dialect": dialect, **opts}
2218
2219        try:
2220            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2221        except ParseError:
2222            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2223
2224        join = expression if isinstance(expression, Join) else Join(this=expression)
2225
2226        if isinstance(join.this, Select):
2227            join.this.replace(join.this.subquery())
2228
2229        if join_type:
2230            natural: t.Optional[Token]
2231            side: t.Optional[Token]
2232            kind: t.Optional[Token]
2233
2234            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2235
2236            if natural:
2237                join.set("natural", True)
2238            if side:
2239                join.set("side", side.text)
2240            if kind:
2241                join.set("kind", kind.text)
2242
2243        if on:
2244            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2245            join.set("on", on)
2246
2247        if using:
2248            join = _apply_list_builder(
2249                *ensure_collection(using),
2250                instance=join,
2251                arg="using",
2252                append=append,
2253                copy=copy,
2254                **opts,
2255            )
2256
2257        if join_alias:
2258            join.set("this", alias_(join.this, join_alias, table=True))
2259        return _apply_list_builder(
2260            join,
2261            instance=self,
2262            arg="joins",
2263            append=append,
2264            copy=copy,
2265            **opts,
2266        )

Append to or set the JOIN expressions.

Example:
>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
>>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
'SELECT 1 FROM a JOIN b USING (x, y, z)'

Use join_type to change the type of join:

>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
Arguments:
  • expression (str | Expression): the SQL code string to parse. If an Expression instance is passed, it will be used as-is.
  • on (str | Expression): optionally specify the join "on" criteria as a SQL string. If an Expression instance is passed, it will be used as-is.
  • using (str | Expression): optionally specify the join "using" criteria as a SQL string. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • join_type (str): If set, alter the parsed join type
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def where( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2268    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2269        """
2270        Append to or set the WHERE expressions.
2271
2272        Example:
2273            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2274            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2275
2276        Args:
2277            *expressions (str | Expression): the SQL code strings to parse.
2278                If an `Expression` instance is passed, it will be used as-is.
2279                Multiple expressions are combined with an AND operator.
2280            append (bool): if `True`, AND the new expressions to any existing expression.
2281                Otherwise, this resets the expression.
2282            dialect (str): the dialect used to parse the input expressions.
2283            copy (bool): if `False`, modify this expression instance in-place.
2284            opts (kwargs): other options to use to parse the input expressions.
2285
2286        Returns:
2287            Select: the modified expression.
2288        """
2289        return _apply_conjunction_builder(
2290            *expressions,
2291            instance=self,
2292            arg="where",
2293            append=append,
2294            into=Where,
2295            dialect=dialect,
2296            copy=copy,
2297            **opts,
2298        )

Append to or set the WHERE expressions.

Example:
>>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
"SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def having( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2300    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2301        """
2302        Append to or set the HAVING expressions.
2303
2304        Example:
2305            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2306            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2307
2308        Args:
2309            *expressions (str | Expression): the SQL code strings to parse.
2310                If an `Expression` instance is passed, it will be used as-is.
2311                Multiple expressions are combined with an AND operator.
2312            append (bool): if `True`, AND the new expressions to any existing expression.
2313                Otherwise, this resets the expression.
2314            dialect (str): the dialect used to parse the input expressions.
2315            copy (bool): if `False`, modify this expression instance in-place.
2316            opts (kwargs): other options to use to parse the input expressions.
2317
2318        Returns:
2319            Select: the modified expression.
2320        """
2321        return _apply_conjunction_builder(
2322            *expressions,
2323            instance=self,
2324            arg="having",
2325            append=append,
2326            into=Having,
2327            dialect=dialect,
2328            copy=copy,
2329            **opts,
2330        )

Append to or set the HAVING expressions.

Example:
>>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def window( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2332    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2333        return _apply_list_builder(
2334            *expressions,
2335            instance=self,
2336            arg="windows",
2337            append=append,
2338            into=Window,
2339            dialect=dialect,
2340            copy=copy,
2341            **opts,
2342        )
def distinct(self, distinct=True, copy=True) -> sqlglot.expressions.Select:
2344    def distinct(self, distinct=True, copy=True) -> Select:
2345        """
2346        Set the OFFSET expression.
2347
2348        Example:
2349            >>> Select().from_("tbl").select("x").distinct().sql()
2350            'SELECT DISTINCT x FROM tbl'
2351
2352        Args:
2353            distinct (bool): whether the Select should be distinct
2354            copy (bool): if `False`, modify this expression instance in-place.
2355
2356        Returns:
2357            Select: the modified expression.
2358        """
2359        instance = _maybe_copy(self, copy)
2360        instance.set("distinct", Distinct() if distinct else None)
2361        return instance

Set the OFFSET expression.

Example:
>>> Select().from_("tbl").select("x").distinct().sql()
'SELECT DISTINCT x FROM tbl'
Arguments:
  • distinct (bool): whether the Select should be distinct
  • copy (bool): if False, modify this expression instance in-place.
Returns:

Select: the modified expression.

def ctas( self, table, properties=None, dialect=None, copy=True, **opts) -> sqlglot.expressions.Create:
2363    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2364        """
2365        Convert this expression to a CREATE TABLE AS statement.
2366
2367        Example:
2368            >>> Select().select("*").from_("tbl").ctas("x").sql()
2369            'CREATE TABLE x AS SELECT * FROM tbl'
2370
2371        Args:
2372            table (str | Expression): the SQL code string to parse as the table name.
2373                If another `Expression` instance is passed, it will be used as-is.
2374            properties (dict): an optional mapping of table properties
2375            dialect (str): the dialect used to parse the input table.
2376            copy (bool): if `False`, modify this expression instance in-place.
2377            opts (kwargs): other options to use to parse the input table.
2378
2379        Returns:
2380            Create: the CREATE TABLE AS expression
2381        """
2382        instance = _maybe_copy(self, copy)
2383        table_expression = maybe_parse(
2384            table,
2385            into=Table,
2386            dialect=dialect,
2387            **opts,
2388        )
2389        properties_expression = None
2390        if properties:
2391            properties_expression = Properties.from_dict(properties)
2392
2393        return Create(
2394            this=table_expression,
2395            kind="table",
2396            expression=instance,
2397            properties=properties_expression,
2398        )

Convert this expression to a CREATE TABLE AS statement.

Example:
>>> Select().select("*").from_("tbl").ctas("x").sql()
'CREATE TABLE x AS SELECT * FROM tbl'
Arguments:
  • table (str | Expression): the SQL code string to parse as the table name. If another Expression instance is passed, it will be used as-is.
  • properties (dict): an optional mapping of table properties
  • dialect (str): the dialect used to parse the input table.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input table.
Returns:

Create: the CREATE TABLE AS expression

def lock( self, update: bool = True, copy: bool = True) -> sqlglot.expressions.Select:
2400    def lock(self, update: bool = True, copy: bool = True) -> Select:
2401        """
2402        Set the locking read mode for this expression.
2403
2404        Examples:
2405            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2406            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2407
2408            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2409            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2410
2411        Args:
2412            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2413            copy: if `False`, modify this expression instance in-place.
2414
2415        Returns:
2416            The modified expression.
2417        """
2418
2419        inst = _maybe_copy(self, copy)
2420        inst.set("lock", Lock(update=update))
2421
2422        return inst

Set the locking read mode for this expression.

Examples:
>>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
"SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
>>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
"SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
Arguments:
  • update: if True, the locking type will be FOR UPDATE, else it will be FOR SHARE.
  • copy: if False, modify this expression instance in-place.
Returns:

The modified expression.

class Subquery(DerivedTable, Unionable):
2433class Subquery(DerivedTable, Unionable):
2434    arg_types = {
2435        "this": True,
2436        "alias": False,
2437        "with": False,
2438        **QUERY_MODIFIERS,
2439    }
2440
2441    def unnest(self):
2442        """
2443        Returns the first non subquery.
2444        """
2445        expression = self
2446        while isinstance(expression, Subquery):
2447            expression = expression.this
2448        return expression
2449
2450    @property
2451    def output_name(self):
2452        return self.alias
def unnest(self):
2441    def unnest(self):
2442        """
2443        Returns the first non subquery.
2444        """
2445        expression = self
2446        while isinstance(expression, Subquery):
2447            expression = expression.this
2448        return expression

Returns the first non subquery.

output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class TableSample(Expression):
2455class TableSample(Expression):
2456    arg_types = {
2457        "this": False,
2458        "method": False,
2459        "bucket_numerator": False,
2460        "bucket_denominator": False,
2461        "bucket_field": False,
2462        "percent": False,
2463        "rows": False,
2464        "size": False,
2465        "seed": False,
2466    }
class Tag(Expression):
2469class Tag(Expression):
2470    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
2471
2472    arg_types = {
2473        "this": False,
2474        "prefix": False,
2475        "postfix": False,
2476    }

Tags are used for generating arbitrary sql like SELECT x.

class Pivot(Expression):
2479class Pivot(Expression):
2480    arg_types = {
2481        "this": False,
2482        "expressions": True,
2483        "field": True,
2484        "unpivot": True,
2485    }
class Window(Expression):
2488class Window(Expression):
2489    arg_types = {
2490        "this": True,
2491        "partition_by": False,
2492        "order": False,
2493        "spec": False,
2494        "alias": False,
2495    }
class WindowSpec(Expression):
2498class WindowSpec(Expression):
2499    arg_types = {
2500        "kind": False,
2501        "start": False,
2502        "start_side": False,
2503        "end": False,
2504        "end_side": False,
2505    }
class Where(Expression):
2508class Where(Expression):
2509    pass
class Star(Expression):
2512class Star(Expression):
2513    arg_types = {"except": False, "replace": False}
2514
2515    @property
2516    def name(self) -> str:
2517        return "*"
2518
2519    @property
2520    def output_name(self):
2521        return self.name
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Parameter(Expression):
2524class Parameter(Expression):
2525    arg_types = {"this": True, "wrapped": False}
class SessionParameter(Expression):
2528class SessionParameter(Expression):
2529    arg_types = {"this": True, "kind": False}
class Placeholder(Expression):
2532class Placeholder(Expression):
2533    arg_types = {"this": False}
class Null(Condition):
2536class Null(Condition):
2537    arg_types: t.Dict[str, t.Any] = {}
2538
2539    @property
2540    def name(self) -> str:
2541        return "NULL"
class Boolean(Condition):
2544class Boolean(Condition):
2545    pass
class DataType(Expression):
2548class DataType(Expression):
2549    arg_types = {
2550        "this": True,
2551        "expressions": False,
2552        "nested": False,
2553        "values": False,
2554        "prefix": False,
2555    }
2556
2557    class Type(AutoName):
2558        CHAR = auto()
2559        NCHAR = auto()
2560        VARCHAR = auto()
2561        NVARCHAR = auto()
2562        TEXT = auto()
2563        MEDIUMTEXT = auto()
2564        LONGTEXT = auto()
2565        MEDIUMBLOB = auto()
2566        LONGBLOB = auto()
2567        BINARY = auto()
2568        VARBINARY = auto()
2569        INT = auto()
2570        TINYINT = auto()
2571        SMALLINT = auto()
2572        BIGINT = auto()
2573        FLOAT = auto()
2574        DOUBLE = auto()
2575        DECIMAL = auto()
2576        BOOLEAN = auto()
2577        JSON = auto()
2578        JSONB = auto()
2579        INTERVAL = auto()
2580        TIME = auto()
2581        TIMESTAMP = auto()
2582        TIMESTAMPTZ = auto()
2583        TIMESTAMPLTZ = auto()
2584        DATE = auto()
2585        DATETIME = auto()
2586        ARRAY = auto()
2587        MAP = auto()
2588        UUID = auto()
2589        GEOGRAPHY = auto()
2590        GEOMETRY = auto()
2591        STRUCT = auto()
2592        NULLABLE = auto()
2593        HLLSKETCH = auto()
2594        HSTORE = auto()
2595        SUPER = auto()
2596        SERIAL = auto()
2597        SMALLSERIAL = auto()
2598        BIGSERIAL = auto()
2599        XML = auto()
2600        UNIQUEIDENTIFIER = auto()
2601        MONEY = auto()
2602        SMALLMONEY = auto()
2603        ROWVERSION = auto()
2604        IMAGE = auto()
2605        VARIANT = auto()
2606        OBJECT = auto()
2607        NULL = auto()
2608        UNKNOWN = auto()  # Sentinel value, useful for type annotation
2609
2610    TEXT_TYPES = {
2611        Type.CHAR,
2612        Type.NCHAR,
2613        Type.VARCHAR,
2614        Type.NVARCHAR,
2615        Type.TEXT,
2616    }
2617
2618    INTEGER_TYPES = {
2619        Type.INT,
2620        Type.TINYINT,
2621        Type.SMALLINT,
2622        Type.BIGINT,
2623    }
2624
2625    FLOAT_TYPES = {
2626        Type.FLOAT,
2627        Type.DOUBLE,
2628    }
2629
2630    NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES}
2631
2632    TEMPORAL_TYPES = {
2633        Type.TIMESTAMP,
2634        Type.TIMESTAMPTZ,
2635        Type.TIMESTAMPLTZ,
2636        Type.DATE,
2637        Type.DATETIME,
2638    }
2639
2640    @classmethod
2641    def build(
2642        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2643    ) -> DataType:
2644        from sqlglot import parse_one
2645
2646        if isinstance(dtype, str):
2647            if dtype.upper() in cls.Type.__members__:
2648                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2649            else:
2650                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2651            if data_type_exp is None:
2652                raise ValueError(f"Unparsable data type value: {dtype}")
2653        elif isinstance(dtype, DataType.Type):
2654            data_type_exp = DataType(this=dtype)
2655        elif isinstance(dtype, DataType):
2656            return dtype
2657        else:
2658            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2659        return DataType(**{**data_type_exp.args, **kwargs})
2660
2661    def is_type(self, dtype: DataType.Type) -> bool:
2662        return self.this == dtype
@classmethod
def build( cls, dtype: str | sqlglot.expressions.DataType | sqlglot.expressions.DataType.Type, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> sqlglot.expressions.DataType:
2640    @classmethod
2641    def build(
2642        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2643    ) -> DataType:
2644        from sqlglot import parse_one
2645
2646        if isinstance(dtype, str):
2647            if dtype.upper() in cls.Type.__members__:
2648                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2649            else:
2650                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2651            if data_type_exp is None:
2652                raise ValueError(f"Unparsable data type value: {dtype}")
2653        elif isinstance(dtype, DataType.Type):
2654            data_type_exp = DataType(this=dtype)
2655        elif isinstance(dtype, DataType):
2656            return dtype
2657        else:
2658            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2659        return DataType(**{**data_type_exp.args, **kwargs})
def is_type(self, dtype: sqlglot.expressions.DataType.Type) -> bool:
2661    def is_type(self, dtype: DataType.Type) -> bool:
2662        return self.this == dtype
class DataType.Type(sqlglot.helper.AutoName):
2557    class Type(AutoName):
2558        CHAR = auto()
2559        NCHAR = auto()
2560        VARCHAR = auto()
2561        NVARCHAR = auto()
2562        TEXT = auto()
2563        MEDIUMTEXT = auto()
2564        LONGTEXT = auto()
2565        MEDIUMBLOB = auto()
2566        LONGBLOB = auto()
2567        BINARY = auto()
2568        VARBINARY = auto()
2569        INT = auto()
2570        TINYINT = auto()
2571        SMALLINT = auto()
2572        BIGINT = auto()
2573        FLOAT = auto()
2574        DOUBLE = auto()
2575        DECIMAL = auto()
2576        BOOLEAN = auto()
2577        JSON = auto()
2578        JSONB = auto()
2579        INTERVAL = auto()
2580        TIME = auto()
2581        TIMESTAMP = auto()
2582        TIMESTAMPTZ = auto()
2583        TIMESTAMPLTZ = auto()
2584        DATE = auto()
2585        DATETIME = auto()
2586        ARRAY = auto()
2587        MAP = auto()
2588        UUID = auto()
2589        GEOGRAPHY = auto()
2590        GEOMETRY = auto()
2591        STRUCT = auto()
2592        NULLABLE = auto()
2593        HLLSKETCH = auto()
2594        HSTORE = auto()
2595        SUPER = auto()
2596        SERIAL = auto()
2597        SMALLSERIAL = auto()
2598        BIGSERIAL = auto()
2599        XML = auto()
2600        UNIQUEIDENTIFIER = auto()
2601        MONEY = auto()
2602        SMALLMONEY = auto()
2603        ROWVERSION = auto()
2604        IMAGE = auto()
2605        VARIANT = auto()
2606        OBJECT = auto()
2607        NULL = auto()
2608        UNKNOWN = auto()  # Sentinel value, useful for type annotation

An enumeration.

CHAR = <Type.CHAR: 'CHAR'>
NCHAR = <Type.NCHAR: 'NCHAR'>
VARCHAR = <Type.VARCHAR: 'VARCHAR'>
NVARCHAR = <Type.NVARCHAR: 'NVARCHAR'>
TEXT = <Type.TEXT: 'TEXT'>
MEDIUMTEXT = <Type.MEDIUMTEXT: 'MEDIUMTEXT'>
LONGTEXT = <Type.LONGTEXT: 'LONGTEXT'>
MEDIUMBLOB = <Type.MEDIUMBLOB: 'MEDIUMBLOB'>
LONGBLOB = <Type.LONGBLOB: 'LONGBLOB'>
BINARY = <Type.BINARY: 'BINARY'>
VARBINARY = <Type.VARBINARY: 'VARBINARY'>
INT = <Type.INT: 'INT'>
TINYINT = <Type.TINYINT: 'TINYINT'>
SMALLINT = <Type.SMALLINT: 'SMALLINT'>
BIGINT = <Type.BIGINT: 'BIGINT'>
FLOAT = <Type.FLOAT: 'FLOAT'>
DOUBLE = <Type.DOUBLE: 'DOUBLE'>
DECIMAL = <Type.DECIMAL: 'DECIMAL'>
BOOLEAN = <Type.BOOLEAN: 'BOOLEAN'>
JSON = <Type.JSON: 'JSON'>
JSONB = <Type.JSONB: 'JSONB'>
INTERVAL = <Type.INTERVAL: 'INTERVAL'>
TIME = <Type.TIME: 'TIME'>
TIMESTAMP = <Type.TIMESTAMP: 'TIMESTAMP'>
TIMESTAMPTZ = <Type.TIMESTAMPTZ: 'TIMESTAMPTZ'>
TIMESTAMPLTZ = <Type.TIMESTAMPLTZ: 'TIMESTAMPLTZ'>
DATE = <Type.DATE: 'DATE'>
DATETIME = <Type.DATETIME: 'DATETIME'>
ARRAY = <Type.ARRAY: 'ARRAY'>
MAP = <Type.MAP: 'MAP'>
UUID = <Type.UUID: 'UUID'>
GEOGRAPHY = <Type.GEOGRAPHY: 'GEOGRAPHY'>
GEOMETRY = <Type.GEOMETRY: 'GEOMETRY'>
STRUCT = <Type.STRUCT: 'STRUCT'>
NULLABLE = <Type.NULLABLE: 'NULLABLE'>
HLLSKETCH = <Type.HLLSKETCH: 'HLLSKETCH'>
HSTORE = <Type.HSTORE: 'HSTORE'>
SUPER = <Type.SUPER: 'SUPER'>
SERIAL = <Type.SERIAL: 'SERIAL'>
SMALLSERIAL = <Type.SMALLSERIAL: 'SMALLSERIAL'>
BIGSERIAL = <Type.BIGSERIAL: 'BIGSERIAL'>
XML = <Type.XML: 'XML'>
UNIQUEIDENTIFIER = <Type.UNIQUEIDENTIFIER: 'UNIQUEIDENTIFIER'>
MONEY = <Type.MONEY: 'MONEY'>
SMALLMONEY = <Type.SMALLMONEY: 'SMALLMONEY'>
ROWVERSION = <Type.ROWVERSION: 'ROWVERSION'>
IMAGE = <Type.IMAGE: 'IMAGE'>
VARIANT = <Type.VARIANT: 'VARIANT'>
OBJECT = <Type.OBJECT: 'OBJECT'>
NULL = <Type.NULL: 'NULL'>
UNKNOWN = <Type.UNKNOWN: 'UNKNOWN'>
Inherited Members
enum.Enum
name
value
class PseudoType(Expression):
2666class PseudoType(Expression):
2667    pass
class StructKwarg(Expression):
2670class StructKwarg(Expression):
2671    arg_types = {"this": True, "expression": True}
class SubqueryPredicate(Predicate):
2675class SubqueryPredicate(Predicate):
2676    pass
class All(SubqueryPredicate):
2679class All(SubqueryPredicate):
2680    pass
class Any(SubqueryPredicate):
2683class Any(SubqueryPredicate):
2684    pass
class Exists(SubqueryPredicate):
2687class Exists(SubqueryPredicate):
2688    pass
class Command(Expression):
2693class Command(Expression):
2694    arg_types = {"this": True, "expression": False}
class Transaction(Expression):
2697class Transaction(Expression):
2698    arg_types = {"this": False, "modes": False}
class Commit(Expression):
2701class Commit(Expression):
2702    arg_types = {"chain": False}
class Rollback(Expression):
2705class Rollback(Expression):
2706    arg_types = {"savepoint": False}
class AlterTable(Expression):
2709class AlterTable(Expression):
2710    arg_types = {"this": True, "actions": True, "exists": False}
class AddConstraint(Expression):
2713class AddConstraint(Expression):
2714    arg_types = {"this": False, "expression": False, "enforced": False}
class DropPartition(Expression):
2717class DropPartition(Expression):
2718    arg_types = {"expressions": True, "exists": False}
class Binary(Expression):
2722class Binary(Expression):
2723    arg_types = {"this": True, "expression": True}
2724
2725    @property
2726    def left(self):
2727        return self.this
2728
2729    @property
2730    def right(self):
2731        return self.expression
class Add(Binary):
2734class Add(Binary):
2735    pass
class Connector(Binary, Condition):
2738class Connector(Binary, Condition):
2739    pass
class And(Connector):
2742class And(Connector):
2743    pass
class Or(Connector):
2746class Or(Connector):
2747    pass
class BitwiseAnd(Binary):
2750class BitwiseAnd(Binary):
2751    pass
class BitwiseLeftShift(Binary):
2754class BitwiseLeftShift(Binary):
2755    pass
class BitwiseOr(Binary):
2758class BitwiseOr(Binary):
2759    pass
class BitwiseRightShift(Binary):
2762class BitwiseRightShift(Binary):
2763    pass
class BitwiseXor(Binary):
2766class BitwiseXor(Binary):
2767    pass
class Div(Binary):
2770class Div(Binary):
2771    pass
class Dot(Binary):
2774class Dot(Binary):
2775    @property
2776    def name(self) -> str:
2777        return self.expression.name
class DPipe(Binary):
2780class DPipe(Binary):
2781    pass
class EQ(Binary, Predicate):
2784class EQ(Binary, Predicate):
2785    pass
class NullSafeEQ(Binary, Predicate):
2788class NullSafeEQ(Binary, Predicate):
2789    pass
class NullSafeNEQ(Binary, Predicate):
2792class NullSafeNEQ(Binary, Predicate):
2793    pass
class Distance(Binary):
2796class Distance(Binary):
2797    pass
class Escape(Binary):
2800class Escape(Binary):
2801    pass
class Glob(Binary, Predicate):
2804class Glob(Binary, Predicate):
2805    pass
class GT(Binary, Predicate):
2808class GT(Binary, Predicate):
2809    pass
class GTE(Binary, Predicate):
2812class GTE(Binary, Predicate):
2813    pass
class ILike(Binary, Predicate):
2816class ILike(Binary, Predicate):
2817    pass
class ILikeAny(Binary, Predicate):
2820class ILikeAny(Binary, Predicate):
2821    pass
class IntDiv(Binary):
2824class IntDiv(Binary):
2825    pass
class Is(Binary, Predicate):
2828class Is(Binary, Predicate):
2829    pass
class Kwarg(Binary):
2832class Kwarg(Binary):
2833    """Kwarg in special functions like func(kwarg => y)."""

Kwarg in special functions like func(kwarg => y).

class Like(Binary, Predicate):
2836class Like(Binary, Predicate):
2837    pass
class LikeAny(Binary, Predicate):
2840class LikeAny(Binary, Predicate):
2841    pass
class LT(Binary, Predicate):
2844class LT(Binary, Predicate):
2845    pass
class LTE(Binary, Predicate):
2848class LTE(Binary, Predicate):
2849    pass
class Mod(Binary):
2852class Mod(Binary):
2853    pass
class Mul(Binary):
2856class Mul(Binary):
2857    pass
class NEQ(Binary, Predicate):
2860class NEQ(Binary, Predicate):
2861    pass
class SimilarTo(Binary, Predicate):
2864class SimilarTo(Binary, Predicate):
2865    pass
class Slice(Binary):
2868class Slice(Binary):
2869    arg_types = {"this": False, "expression": False}
class Sub(Binary):
2872class Sub(Binary):
2873    pass
class Unary(Expression):
2878class Unary(Expression):
2879    pass
class BitwiseNot(Unary):
2882class BitwiseNot(Unary):
2883    pass
class Not(Unary, Condition):
2886class Not(Unary, Condition):
2887    pass
class Paren(Unary, Condition):
2890class Paren(Unary, Condition):
2891    arg_types = {"this": True, "with": False}
class Neg(Unary):
2894class Neg(Unary):
2895    pass
class Alias(Expression):
2899class Alias(Expression):
2900    arg_types = {"this": True, "alias": False}
2901
2902    @property
2903    def output_name(self):
2904        return self.alias
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Aliases(Expression):
2907class Aliases(Expression):
2908    arg_types = {"this": True, "expressions": True}
2909
2910    @property
2911    def aliases(self):
2912        return self.expressions
class AtTimeZone(Expression):
2915class AtTimeZone(Expression):
2916    arg_types = {"this": True, "zone": True}
class Between(Predicate):
2919class Between(Predicate):
2920    arg_types = {"this": True, "low": True, "high": True}
class Bracket(Condition):
2923class Bracket(Condition):
2924    arg_types = {"this": True, "expressions": True}
class Distinct(Expression):
2927class Distinct(Expression):
2928    arg_types = {"expressions": False, "on": False}
class In(Predicate):
2931class In(Predicate):
2932    arg_types = {
2933        "this": True,
2934        "expressions": False,
2935        "query": False,
2936        "unnest": False,
2937        "field": False,
2938        "is_global": False,
2939    }
class TimeUnit(Expression):
2942class TimeUnit(Expression):
2943    """Automatically converts unit arg into a var."""
2944
2945    arg_types = {"unit": False}
2946
2947    def __init__(self, **args):
2948        unit = args.get("unit")
2949        if isinstance(unit, Column):
2950            args["unit"] = Var(this=unit.name)
2951        elif isinstance(unit, Week):
2952            unit.set("this", Var(this=unit.this.name))
2953        super().__init__(**args)

Automatically converts unit arg into a var.

TimeUnit(**args)
2947    def __init__(self, **args):
2948        unit = args.get("unit")
2949        if isinstance(unit, Column):
2950            args["unit"] = Var(this=unit.name)
2951        elif isinstance(unit, Week):
2952            unit.set("this", Var(this=unit.this.name))
2953        super().__init__(**args)
class Interval(TimeUnit):
2956class Interval(TimeUnit):
2957    arg_types = {"this": False, "unit": False}
class IgnoreNulls(Expression):
2960class IgnoreNulls(Expression):
2961    pass
class RespectNulls(Expression):
2964class RespectNulls(Expression):
2965    pass
class Func(Condition):
2969class Func(Condition):
2970    """
2971    The base class for all function expressions.
2972
2973    Attributes:
2974        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
2975            treated as a variable length argument and the argument's value will be stored as a list.
2976        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
2977            for this function expression. These values are used to map this node to a name during parsing
2978            as well as to provide the function's name during SQL string generation. By default the SQL
2979            name is set to the expression's class name transformed to snake case.
2980    """
2981
2982    is_var_len_args = False
2983
2984    @classmethod
2985    def from_arg_list(cls, args):
2986        if cls.is_var_len_args:
2987            all_arg_keys = list(cls.arg_types)
2988            # If this function supports variable length argument treat the last argument as such.
2989            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
2990            num_non_var = len(non_var_len_arg_keys)
2991
2992            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
2993            args_dict[all_arg_keys[-1]] = args[num_non_var:]
2994        else:
2995            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
2996
2997        return cls(**args_dict)
2998
2999    @classmethod
3000    def sql_names(cls):
3001        if cls is Func:
3002            raise NotImplementedError(
3003                "SQL name is only supported by concrete function implementations"
3004            )
3005        if "_sql_names" not in cls.__dict__:
3006            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3007        return cls._sql_names
3008
3009    @classmethod
3010    def sql_name(cls):
3011        return cls.sql_names()[0]
3012
3013    @classmethod
3014    def default_parser_mappings(cls):
3015        return {name: cls.from_arg_list for name in cls.sql_names()}

The base class for all function expressions.

Attributes:
  • is_var_len_args (bool): if set to True the last argument defined in arg_types will be treated as a variable length argument and the argument's value will be stored as a list.
  • _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) for this function expression. These values are used to map this node to a name during parsing as well as to provide the function's name during SQL string generation. By default the SQL name is set to the expression's class name transformed to snake case.
@classmethod
def from_arg_list(cls, args):
2984    @classmethod
2985    def from_arg_list(cls, args):
2986        if cls.is_var_len_args:
2987            all_arg_keys = list(cls.arg_types)
2988            # If this function supports variable length argument treat the last argument as such.
2989            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
2990            num_non_var = len(non_var_len_arg_keys)
2991
2992            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
2993            args_dict[all_arg_keys[-1]] = args[num_non_var:]
2994        else:
2995            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
2996
2997        return cls(**args_dict)
@classmethod
def sql_names(cls):
2999    @classmethod
3000    def sql_names(cls):
3001        if cls is Func:
3002            raise NotImplementedError(
3003                "SQL name is only supported by concrete function implementations"
3004            )
3005        if "_sql_names" not in cls.__dict__:
3006            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3007        return cls._sql_names
@classmethod
def sql_name(cls):
3009    @classmethod
3010    def sql_name(cls):
3011        return cls.sql_names()[0]
@classmethod
def default_parser_mappings(cls):
3013    @classmethod
3014    def default_parser_mappings(cls):
3015        return {name: cls.from_arg_list for name in cls.sql_names()}
class AggFunc(Func):
3018class AggFunc(Func):
3019    pass
class Abs(Func):
3022class Abs(Func):
3023    pass
class Anonymous(Func):
3026class Anonymous(Func):
3027    arg_types = {"this": True, "expressions": False}
3028    is_var_len_args = True
class ApproxDistinct(AggFunc):
3031class ApproxDistinct(AggFunc):
3032    arg_types = {"this": True, "accuracy": False}
class Array(Func):
3035class Array(Func):
3036    arg_types = {"expressions": False}
3037    is_var_len_args = True
class GenerateSeries(Func):
3040class GenerateSeries(Func):
3041    arg_types = {"start": True, "end": True, "step": False}
class ArrayAgg(AggFunc):
3044class ArrayAgg(AggFunc):
3045    pass
class ArrayAll(Func):
3048class ArrayAll(Func):
3049    arg_types = {"this": True, "expression": True}
class ArrayAny(Func):
3052class ArrayAny(Func):
3053    arg_types = {"this": True, "expression": True}
class ArrayConcat(Func):
3056class ArrayConcat(Func):
3057    arg_types = {"this": True, "expressions": False}
3058    is_var_len_args = True
class ArrayContains(Func):
3061class ArrayContains(Func):
3062    arg_types = {"this": True, "expression": True}
class ArrayFilter(Func):
3065class ArrayFilter(Func):
3066    arg_types = {"this": True, "expression": True}
3067    _sql_names = ["FILTER", "ARRAY_FILTER"]
class ArraySize(Func):
3070class ArraySize(Func):
3071    arg_types = {"this": True, "expression": False}
class ArraySort(Func):
3074class ArraySort(Func):
3075    arg_types = {"this": True, "expression": False}
class ArraySum(Func):
3078class ArraySum(Func):
3079    pass
class ArrayUnionAgg(AggFunc):
3082class ArrayUnionAgg(AggFunc):
3083    pass
class Avg(AggFunc):
3086class Avg(AggFunc):
3087    pass
class AnyValue(AggFunc):
3090class AnyValue(AggFunc):
3091    pass
class Case(Func):
3094class Case(Func):
3095    arg_types = {"this": False, "ifs": True, "default": False}
class Cast(Func):
3098class Cast(Func):
3099    arg_types = {"this": True, "to": True}
3100
3101    @property
3102    def name(self) -> str:
3103        return self.this.name
3104
3105    @property
3106    def to(self):
3107        return self.args["to"]
3108
3109    @property
3110    def output_name(self):
3111        return self.name
3112
3113    def is_type(self, dtype: DataType.Type) -> bool:
3114        return self.to.is_type(dtype)
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
def is_type(self, dtype: sqlglot.expressions.DataType.Type) -> bool:
3113    def is_type(self, dtype: DataType.Type) -> bool:
3114        return self.to.is_type(dtype)
class Collate(Binary):
3117class Collate(Binary):
3118    pass
class TryCast(Cast):
3121class TryCast(Cast):
3122    pass
class Ceil(Func):
3125class Ceil(Func):
3126    arg_types = {"this": True, "decimals": False}
3127    _sql_names = ["CEIL", "CEILING"]
class Coalesce(Func):
3130class Coalesce(Func):
3131    arg_types = {"this": True, "expressions": False}
3132    is_var_len_args = True
class Concat(Func):
3135class Concat(Func):
3136    arg_types = {"expressions": True}
3137    is_var_len_args = True
class ConcatWs(Concat):
3140class ConcatWs(Concat):
3141    _sql_names = ["CONCAT_WS"]
class Count(AggFunc):
3144class Count(AggFunc):
3145    arg_types = {"this": False}
class CurrentDate(Func):
3148class CurrentDate(Func):
3149    arg_types = {"this": False}
class CurrentDatetime(Func):
3152class CurrentDatetime(Func):
3153    arg_types = {"this": False}
class CurrentTime(Func):
3156class CurrentTime(Func):
3157    arg_types = {"this": False}
class CurrentTimestamp(Func):
3160class CurrentTimestamp(Func):
3161    arg_types = {"this": False}
class DateAdd(Func, TimeUnit):
3164class DateAdd(Func, TimeUnit):
3165    arg_types = {"this": True, "expression": True, "unit": False}
class DateSub(Func, TimeUnit):
3168class DateSub(Func, TimeUnit):
3169    arg_types = {"this": True, "expression": True, "unit": False}
class DateDiff(Func, TimeUnit):
3172class DateDiff(Func, TimeUnit):
3173    arg_types = {"this": True, "expression": True, "unit": False}
class DateTrunc(Func):
3176class DateTrunc(Func):
3177    arg_types = {"unit": True, "this": True, "zone": False}
class DatetimeAdd(Func, TimeUnit):
3180class DatetimeAdd(Func, TimeUnit):
3181    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeSub(Func, TimeUnit):
3184class DatetimeSub(Func, TimeUnit):
3185    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeDiff(Func, TimeUnit):
3188class DatetimeDiff(Func, TimeUnit):
3189    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeTrunc(Func, TimeUnit):
3192class DatetimeTrunc(Func, TimeUnit):
3193    arg_types = {"this": True, "unit": True, "zone": False}
class DayOfWeek(Func):
3196class DayOfWeek(Func):
3197    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
class DayOfMonth(Func):
3200class DayOfMonth(Func):
3201    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
class DayOfYear(Func):
3204class DayOfYear(Func):
3205    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
class WeekOfYear(Func):
3208class WeekOfYear(Func):
3209    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
class LastDateOfMonth(Func):
3212class LastDateOfMonth(Func):
3213    pass
class Extract(Func):
3216class Extract(Func):
3217    arg_types = {"this": True, "expression": True}
class TimestampAdd(Func, TimeUnit):
3220class TimestampAdd(Func, TimeUnit):
3221    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampSub(Func, TimeUnit):
3224class TimestampSub(Func, TimeUnit):
3225    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampDiff(Func, TimeUnit):
3228class TimestampDiff(Func, TimeUnit):
3229    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampTrunc(Func, TimeUnit):
3232class TimestampTrunc(Func, TimeUnit):
3233    arg_types = {"this": True, "unit": True, "zone": False}
class TimeAdd(Func, TimeUnit):
3236class TimeAdd(Func, TimeUnit):
3237    arg_types = {"this": True, "expression": True, "unit": False}
class TimeSub(Func, TimeUnit):
3240class TimeSub(Func, TimeUnit):
3241    arg_types = {"this": True, "expression": True, "unit": False}
class TimeDiff(Func, TimeUnit):
3244class TimeDiff(Func, TimeUnit):
3245    arg_types = {"this": True, "expression": True, "unit": False}
class TimeTrunc(Func, TimeUnit):
3248class TimeTrunc(Func, TimeUnit):
3249    arg_types = {"this": True, "unit": True, "zone": False}
class DateFromParts(Func):
3252class DateFromParts(Func):
3253    _sql_names = ["DATEFROMPARTS"]
3254    arg_types = {"year": True, "month": True, "day": True}
class DateStrToDate(Func):
3257class DateStrToDate(Func):
3258    pass
class DateToDateStr(Func):
3261class DateToDateStr(Func):
3262    pass
class DateToDi(Func):
3265class DateToDi(Func):
3266    pass
class Day(Func):
3269class Day(Func):
3270    pass
class Decode(Func):
3273class Decode(Func):
3274    arg_types = {"this": True, "charset": True, "replace": False}
class DiToDate(Func):
3277class DiToDate(Func):
3278    pass
class Encode(Func):
3281class Encode(Func):
3282    arg_types = {"this": True, "charset": True}
class Exp(Func):
3285class Exp(Func):
3286    pass
class Explode(Func):
3289class Explode(Func):
3290    pass
class Floor(Func):
3293class Floor(Func):
3294    arg_types = {"this": True, "decimals": False}
class Greatest(Func):
3297class Greatest(Func):
3298    arg_types = {"this": True, "expressions": False}
3299    is_var_len_args = True
class GroupConcat(Func):
3302class GroupConcat(Func):
3303    arg_types = {"this": True, "separator": False}
class Hex(Func):
3306class Hex(Func):
3307    pass
class If(Func):
3310class If(Func):
3311    arg_types = {"this": True, "true": True, "false": False}
class IfNull(Func):
3314class IfNull(Func):
3315    arg_types = {"this": True, "expression": False}
3316    _sql_names = ["IFNULL", "NVL"]
class Initcap(Func):
3319class Initcap(Func):
3320    pass
class JSONBContains(Binary):
3323class JSONBContains(Binary):
3324    _sql_names = ["JSONB_CONTAINS"]
class JSONExtract(Binary, Func):
3327class JSONExtract(Binary, Func):
3328    _sql_names = ["JSON_EXTRACT"]
class JSONExtractScalar(JSONExtract):
3331class JSONExtractScalar(JSONExtract):
3332    _sql_names = ["JSON_EXTRACT_SCALAR"]
class JSONBExtract(JSONExtract):
3335class JSONBExtract(JSONExtract):
3336    _sql_names = ["JSONB_EXTRACT"]
class JSONBExtractScalar(JSONExtract):
3339class JSONBExtractScalar(JSONExtract):
3340    _sql_names = ["JSONB_EXTRACT_SCALAR"]
class Least(Func):
3343class Least(Func):
3344    arg_types = {"this": True, "expressions": False}
3345    is_var_len_args = True
class Length(Func):
3348class Length(Func):
3349    pass
class Levenshtein(Func):
3352class Levenshtein(Func):
3353    arg_types = {
3354        "this": True,
3355        "expression": False,
3356        "ins_cost": False,
3357        "del_cost": False,
3358        "sub_cost": False,
3359    }
class Ln(Func):
3362class Ln(Func):
3363    pass
class Log(Func):
3366class Log(Func):
3367    arg_types = {"this": True, "expression": False}
class Log2(Func):
3370class Log2(Func):
3371    pass
class Log10(Func):
3374class Log10(Func):
3375    pass
class LogicalOr(AggFunc):
3378class LogicalOr(AggFunc):
3379    _sql_names = ["LOGICAL_OR", "BOOL_OR"]
class Lower(Func):
3382class Lower(Func):
3383    _sql_names = ["LOWER", "LCASE"]
class Map(Func):
3386class Map(Func):
3387    arg_types = {"keys": False, "values": False}
class VarMap(Func):
3390class VarMap(Func):
3391    arg_types = {"keys": True, "values": True}
3392    is_var_len_args = True
class Matches(Func):
3395class Matches(Func):
3396    """Oracle/Snowflake decode.
3397    https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm
3398    Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)
3399    """
3400
3401    arg_types = {"this": True, "expressions": True}
3402    is_var_len_args = True

Oracle/Snowflake decode. https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)

class Max(AggFunc):
3405class Max(AggFunc):
3406    arg_types = {"this": True, "expression": False}
class Min(AggFunc):
3409class Min(AggFunc):
3410    arg_types = {"this": True, "expression": False}
class Month(Func):
3413class Month(Func):
3414    pass
class Nvl2(Func):
3417class Nvl2(Func):
3418    arg_types = {"this": True, "true": True, "false": False}
class Posexplode(Func):
3421class Posexplode(Func):
3422    pass
class Pow(Binary, Func):
3425class Pow(Binary, Func):
3426    _sql_names = ["POWER", "POW"]
class PercentileCont(AggFunc):
3429class PercentileCont(AggFunc):
3430    pass
class PercentileDisc(AggFunc):
3433class PercentileDisc(AggFunc):
3434    pass
class Quantile(AggFunc):
3437class Quantile(AggFunc):
3438    arg_types = {"this": True, "quantile": True}
class Quantiles(AggFunc):
3443class Quantiles(AggFunc):
3444    arg_types = {"parameters": True, "expressions": True}
class QuantileIf(AggFunc):
3447class QuantileIf(AggFunc):
3448    arg_types = {"parameters": True, "expressions": True}
class ApproxQuantile(Quantile):
3451class ApproxQuantile(Quantile):
3452    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
class ReadCSV(Func):
3455class ReadCSV(Func):
3456    _sql_names = ["READ_CSV"]
3457    is_var_len_args = True
3458    arg_types = {"this": True, "expressions": False}
class Reduce(Func):
3461class Reduce(Func):
3462    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
class RegexpExtract(Func):
3465class RegexpExtract(Func):
3466    arg_types = {
3467        "this": True,
3468        "expression": True,
3469        "position": False,
3470        "occurrence": False,
3471        "group": False,
3472    }
class RegexpLike(Func):
3475class RegexpLike(Func):
3476    arg_types = {"this": True, "expression": True, "flag": False}
class RegexpILike(Func):
3479class RegexpILike(Func):
3480    arg_types = {"this": True, "expression": True, "flag": False}
class RegexpSplit(Func):
3483class RegexpSplit(Func):
3484    arg_types = {"this": True, "expression": True}
class Repeat(Func):
3487class Repeat(Func):
3488    arg_types = {"this": True, "times": True}
class Round(Func):
3491class Round(Func):
3492    arg_types = {"this": True, "decimals": False}
class RowNumber(Func):
3495class RowNumber(Func):
3496    arg_types: t.Dict[str, t.Any] = {}
class SafeDivide(Func):
3499class SafeDivide(Func):
3500    arg_types = {"this": True, "expression": True}
class SetAgg(AggFunc):
3503class SetAgg(AggFunc):
3504    pass
class SortArray(Func):
3507class SortArray(Func):
3508    arg_types = {"this": True, "asc": False}
class Split(Func):
3511class Split(Func):
3512    arg_types = {"this": True, "expression": True, "limit": False}
class Substring(Func):
3517class Substring(Func):
3518    arg_types = {"this": True, "start": False, "length": False}
class StrPosition(Func):
3521class StrPosition(Func):
3522    arg_types = {
3523        "this": True,
3524        "substr": True,
3525        "position": False,
3526        "instance": False,
3527    }
class StrToDate(Func):
3530class StrToDate(Func):
3531    arg_types = {"this": True, "format": True}
class StrToTime(Func):
3534class StrToTime(Func):
3535    arg_types = {"this": True, "format": True}
class StrToUnix(Func):
3540class StrToUnix(Func):
3541    arg_types = {"this": False, "format": False}
class NumberToStr(Func):
3544class NumberToStr(Func):
3545    arg_types = {"this": True, "format": True}
class Struct(Func):
3548class Struct(Func):
3549    arg_types = {"expressions": True}
3550    is_var_len_args = True
class StructExtract(Func):
3553class StructExtract(Func):
3554    arg_types = {"this": True, "expression": True}
class Sum(AggFunc):
3557class Sum(AggFunc):
3558    pass
class Sqrt(Func):
3561class Sqrt(Func):
3562    pass
class Stddev(AggFunc):
3565class Stddev(AggFunc):
3566    pass
class StddevPop(AggFunc):
3569class StddevPop(AggFunc):
3570    pass
class StddevSamp(AggFunc):
3573class StddevSamp(AggFunc):
3574    pass
class TimeToStr(Func):
3577class TimeToStr(Func):
3578    arg_types = {"this": True, "format": True}
class TimeToTimeStr(Func):
3581class TimeToTimeStr(Func):
3582    pass
class TimeToUnix(Func):
3585class TimeToUnix(Func):
3586    pass
class TimeStrToDate(Func):
3589class TimeStrToDate(Func):
3590    pass
class TimeStrToTime(Func):
3593class TimeStrToTime(Func):
3594    pass
class TimeStrToUnix(Func):
3597class TimeStrToUnix(Func):
3598    pass
class Trim(Func):
3601class Trim(Func):
3602    arg_types = {
3603        "this": True,
3604        "expression": False,
3605        "position": False,
3606        "collation": False,
3607    }
class TsOrDsAdd(Func, TimeUnit):
3610class TsOrDsAdd(Func, TimeUnit):
3611    arg_types = {"this": True, "expression": True, "unit": False}
class TsOrDsToDateStr(Func):
3614class TsOrDsToDateStr(Func):
3615    pass
class TsOrDsToDate(Func):
3618class TsOrDsToDate(Func):
3619    arg_types = {"this": True, "format": False}
class TsOrDiToDi(Func):
3622class TsOrDiToDi(Func):
3623    pass
class Unhex(Func):
3626class Unhex(Func):
3627    pass
class UnixToStr(Func):
3630class UnixToStr(Func):
3631    arg_types = {"this": True, "format": False}
class UnixToTime(Func):
3636class UnixToTime(Func):
3637    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
3638
3639    SECONDS = Literal.string("seconds")
3640    MILLIS = Literal.string("millis")
3641    MICROS = Literal.string("micros")
class UnixToTimeStr(Func):
3644class UnixToTimeStr(Func):
3645    pass
class Upper(Func):
3648class Upper(Func):
3649    _sql_names = ["UPPER", "UCASE"]
class Variance(AggFunc):
3652class Variance(AggFunc):
3653    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
class VariancePop(AggFunc):
3656class VariancePop(AggFunc):
3657    _sql_names = ["VARIANCE_POP", "VAR_POP"]
class Week(Func):
3660class Week(Func):
3661    arg_types = {"this": True, "mode": False}
class XMLTable(Func):
3664class XMLTable(Func):
3665    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
class Year(Func):
3668class Year(Func):
3669    pass
class Use(Expression):
3672class Use(Expression):
3673    arg_types = {"this": True, "kind": False}
class Merge(Expression):
3676class Merge(Expression):
3677    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
class When(Func):
3680class When(Func):
3681    arg_types = {"this": True, "then": True}
def maybe_parse( sql_or_expression: str | sqlglot.expressions.Expression, *, into: Union[str, Type[sqlglot.expressions.Expression], Collection[Union[str, Type[sqlglot.expressions.Expression]]], NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, prefix: Optional[str] = None, copy: bool = False, **opts) -> sqlglot.expressions.Expression:
3709def maybe_parse(
3710    sql_or_expression: str | Expression,
3711    *,
3712    into: t.Optional[IntoType] = None,
3713    dialect: DialectType = None,
3714    prefix: t.Optional[str] = None,
3715    copy: bool = False,
3716    **opts,
3717) -> Expression:
3718    """Gracefully handle a possible string or expression.
3719
3720    Example:
3721        >>> maybe_parse("1")
3722        (LITERAL this: 1, is_string: False)
3723        >>> maybe_parse(to_identifier("x"))
3724        (IDENTIFIER this: x, quoted: False)
3725
3726    Args:
3727        sql_or_expression: the SQL code string or an expression
3728        into: the SQLGlot Expression to parse into
3729        dialect: the dialect used to parse the input expressions (in the case that an
3730            input expression is a SQL string).
3731        prefix: a string to prefix the sql with before it gets parsed
3732            (automatically includes a space)
3733        copy: whether or not to copy the expression.
3734        **opts: other options to use to parse the input expressions (again, in the case
3735            that an input expression is a SQL string).
3736
3737    Returns:
3738        Expression: the parsed or given expression.
3739    """
3740    if isinstance(sql_or_expression, Expression):
3741        if copy:
3742            return sql_or_expression.copy()
3743        return sql_or_expression
3744
3745    import sqlglot
3746
3747    sql = str(sql_or_expression)
3748    if prefix:
3749        sql = f"{prefix} {sql}"
3750    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)

Gracefully handle a possible string or expression.

Example:
>>> maybe_parse("1")
(LITERAL this: 1, is_string: False)
>>> maybe_parse(to_identifier("x"))
(IDENTIFIER this: x, quoted: False)
Arguments:
  • sql_or_expression: the SQL code string or an expression
  • into: the SQLGlot Expression to parse into
  • dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
  • prefix: a string to prefix the sql with before it gets parsed (automatically includes a space)
  • copy: whether or not to copy the expression.
  • **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:

Expression: the parsed or given expression.

def union(left, right, distinct=True, dialect=None, **opts):
3896def union(left, right, distinct=True, dialect=None, **opts):
3897    """
3898    Initializes a syntax tree from one UNION expression.
3899
3900    Example:
3901        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
3902        'SELECT * FROM foo UNION SELECT * FROM bla'
3903
3904    Args:
3905        left (str | Expression): the SQL code string corresponding to the left-hand side.
3906            If an `Expression` instance is passed, it will be used as-is.
3907        right (str | Expression): the SQL code string corresponding to the right-hand side.
3908            If an `Expression` instance is passed, it will be used as-is.
3909        distinct (bool): set the DISTINCT flag if and only if this is true.
3910        dialect (str): the dialect used to parse the input expression.
3911        opts (kwargs): other options to use to parse the input expressions.
3912    Returns:
3913        Union: the syntax tree for the UNION expression.
3914    """
3915    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3916    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3917
3918    return Union(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one UNION expression.

Example:
>>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Union: the syntax tree for the UNION expression.

def intersect(left, right, distinct=True, dialect=None, **opts):
3921def intersect(left, right, distinct=True, dialect=None, **opts):
3922    """
3923    Initializes a syntax tree from one INTERSECT expression.
3924
3925    Example:
3926        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
3927        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
3928
3929    Args:
3930        left (str | Expression): the SQL code string corresponding to the left-hand side.
3931            If an `Expression` instance is passed, it will be used as-is.
3932        right (str | Expression): the SQL code string corresponding to the right-hand side.
3933            If an `Expression` instance is passed, it will be used as-is.
3934        distinct (bool): set the DISTINCT flag if and only if this is true.
3935        dialect (str): the dialect used to parse the input expression.
3936        opts (kwargs): other options to use to parse the input expressions.
3937    Returns:
3938        Intersect: the syntax tree for the INTERSECT expression.
3939    """
3940    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3941    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3942
3943    return Intersect(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one INTERSECT expression.

Example:
>>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Intersect: the syntax tree for the INTERSECT expression.

def except_(left, right, distinct=True, dialect=None, **opts):
3946def except_(left, right, distinct=True, dialect=None, **opts):
3947    """
3948    Initializes a syntax tree from one EXCEPT expression.
3949
3950    Example:
3951        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
3952        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
3953
3954    Args:
3955        left (str | Expression): the SQL code string corresponding to the left-hand side.
3956            If an `Expression` instance is passed, it will be used as-is.
3957        right (str | Expression): the SQL code string corresponding to the right-hand side.
3958            If an `Expression` instance is passed, it will be used as-is.
3959        distinct (bool): set the DISTINCT flag if and only if this is true.
3960        dialect (str): the dialect used to parse the input expression.
3961        opts (kwargs): other options to use to parse the input expressions.
3962    Returns:
3963        Except: the syntax tree for the EXCEPT statement.
3964    """
3965    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3966    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3967
3968    return Except(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one EXCEPT expression.

Example:
>>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Except: the syntax tree for the EXCEPT statement.

def select( *expressions: str | sqlglot.expressions.Expression, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> sqlglot.expressions.Select:
3971def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select:
3972    """
3973    Initializes a syntax tree from one or multiple SELECT expressions.
3974
3975    Example:
3976        >>> select("col1", "col2").from_("tbl").sql()
3977        'SELECT col1, col2 FROM tbl'
3978
3979    Args:
3980        *expressions: the SQL code string to parse as the expressions of a
3981            SELECT statement. If an Expression instance is passed, this is used as-is.
3982        dialect: the dialect used to parse the input expressions (in the case that an
3983            input expression is a SQL string).
3984        **opts: other options to use to parse the input expressions (again, in the case
3985            that an input expression is a SQL string).
3986
3987    Returns:
3988        Select: the syntax tree for the SELECT statement.
3989    """
3990    return Select().select(*expressions, dialect=dialect, **opts)

Initializes a syntax tree from one or multiple SELECT expressions.

Example:
>>> select("col1", "col2").from_("tbl").sql()
'SELECT col1, col2 FROM tbl'
Arguments:
  • *expressions: the SQL code string to parse as the expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:

Select: the syntax tree for the SELECT statement.

def from_(*expressions, dialect=None, **opts) -> sqlglot.expressions.Select:
3993def from_(*expressions, dialect=None, **opts) -> Select:
3994    """
3995    Initializes a syntax tree from a FROM expression.
3996
3997    Example:
3998        >>> from_("tbl").select("col1", "col2").sql()
3999        'SELECT col1, col2 FROM tbl'
4000
4001    Args:
4002        *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a
4003            SELECT statement. If an Expression instance is passed, this is used as-is.
4004        dialect (str): the dialect used to parse the input expression (in the case that the
4005            input expression is a SQL string).
4006        **opts: other options to use to parse the input expressions (again, in the case
4007            that the input expression is a SQL string).
4008
4009    Returns:
4010        Select: the syntax tree for the SELECT statement.
4011    """
4012    return Select().from_(*expressions, dialect=dialect, **opts)

Initializes a syntax tree from a FROM expression.

Example:
>>> from_("tbl").select("col1", "col2").sql()
'SELECT col1, col2 FROM tbl'
Arguments:
  • *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:

Select: the syntax tree for the SELECT statement.

def update( table, properties, where=None, from_=None, dialect=None, **opts) -> sqlglot.expressions.Update:
4015def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update:
4016    """
4017    Creates an update statement.
4018
4019    Example:
4020        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
4021        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
4022
4023    Args:
4024        *properties (Dict[str, Any]): dictionary of properties to set which are
4025            auto converted to sql objects eg None -> NULL
4026        where (str): sql conditional parsed into a WHERE statement
4027        from_ (str): sql statement parsed into a FROM statement
4028        dialect (str): the dialect used to parse the input expressions.
4029        **opts: other options to use to parse the input expressions.
4030
4031    Returns:
4032        Update: the syntax tree for the UPDATE statement.
4033    """
4034    update = Update(this=maybe_parse(table, into=Table, dialect=dialect))
4035    update.set(
4036        "expressions",
4037        [
4038            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
4039            for k, v in properties.items()
4040        ],
4041    )
4042    if from_:
4043        update.set(
4044            "from",
4045            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
4046        )
4047    if isinstance(where, Condition):
4048        where = Where(this=where)
4049    if where:
4050        update.set(
4051            "where",
4052            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4053        )
4054    return update

Creates an update statement.

Example:
>>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
"UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
Arguments:
  • *properties (Dict[str, Any]): dictionary of properties to set which are auto converted to sql objects eg None -> NULL
  • where (str): sql conditional parsed into a WHERE statement
  • from_ (str): sql statement parsed into a FROM statement
  • dialect (str): the dialect used to parse the input expressions.
  • **opts: other options to use to parse the input expressions.
Returns:

Update: the syntax tree for the UPDATE statement.

def delete(table, where=None, dialect=None, **opts) -> sqlglot.expressions.Delete:
4057def delete(table, where=None, dialect=None, **opts) -> Delete:
4058    """
4059    Builds a delete statement.
4060
4061    Example:
4062        >>> delete("my_table", where="id > 1").sql()
4063        'DELETE FROM my_table WHERE id > 1'
4064
4065    Args:
4066        where (str|Condition): sql conditional parsed into a WHERE statement
4067        dialect (str): the dialect used to parse the input expressions.
4068        **opts: other options to use to parse the input expressions.
4069
4070    Returns:
4071        Delete: the syntax tree for the DELETE statement.
4072    """
4073    return Delete(
4074        this=maybe_parse(table, into=Table, dialect=dialect, **opts),
4075        where=Where(this=where)
4076        if isinstance(where, Condition)
4077        else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4078    )

Builds a delete statement.

Example:
>>> delete("my_table", where="id > 1").sql()
'DELETE FROM my_table WHERE id > 1'
Arguments:
  • where (str|Condition): sql conditional parsed into a WHERE statement
  • dialect (str): the dialect used to parse the input expressions.
  • **opts: other options to use to parse the input expressions.
Returns:

Delete: the syntax tree for the DELETE statement.

def condition(expression, dialect=None, **opts) -> sqlglot.expressions.Condition:
4081def condition(expression, dialect=None, **opts) -> Condition:
4082    """
4083    Initialize a logical condition expression.
4084
4085    Example:
4086        >>> condition("x=1").sql()
4087        'x = 1'
4088
4089        This is helpful for composing larger logical syntax trees:
4090        >>> where = condition("x=1")
4091        >>> where = where.and_("y=1")
4092        >>> Select().from_("tbl").select("*").where(where).sql()
4093        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
4094
4095    Args:
4096        *expression (str | Expression): the SQL code string to parse.
4097            If an Expression instance is passed, this is used as-is.
4098        dialect (str): the dialect used to parse the input expression (in the case that the
4099            input expression is a SQL string).
4100        **opts: other options to use to parse the input expressions (again, in the case
4101            that the input expression is a SQL string).
4102
4103    Returns:
4104        Condition: the expression
4105    """
4106    return maybe_parse(  # type: ignore
4107        expression,
4108        into=Condition,
4109        dialect=dialect,
4110        **opts,
4111    )

Initialize a logical condition expression.

Example:
>>> condition("x=1").sql()
'x = 1'

This is helpful for composing larger logical syntax trees:

>>> where = condition("x=1")
>>> where = where.and_("y=1")
>>> Select().from_("tbl").select("*").where(where).sql()
'SELECT * FROM tbl WHERE x = 1 AND y = 1'
Arguments:
  • *expression (str | Expression): the SQL code string to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:

Condition: the expression

def and_(*expressions, dialect=None, **opts) -> sqlglot.expressions.And:
4114def and_(*expressions, dialect=None, **opts) -> And:
4115    """
4116    Combine multiple conditions with an AND logical operator.
4117
4118    Example:
4119        >>> and_("x=1", and_("y=1", "z=1")).sql()
4120        'x = 1 AND (y = 1 AND z = 1)'
4121
4122    Args:
4123        *expressions (str | Expression): the SQL code strings to parse.
4124            If an Expression instance is passed, this is used as-is.
4125        dialect (str): the dialect used to parse the input expression.
4126        **opts: other options to use to parse the input expressions.
4127
4128    Returns:
4129        And: the new condition
4130    """
4131    return _combine(expressions, And, dialect, **opts)

Combine multiple conditions with an AND logical operator.

Example:
>>> and_("x=1", and_("y=1", "z=1")).sql()
'x = 1 AND (y = 1 AND z = 1)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

And: the new condition

def or_(*expressions, dialect=None, **opts) -> sqlglot.expressions.Or:
4134def or_(*expressions, dialect=None, **opts) -> Or:
4135    """
4136    Combine multiple conditions with an OR logical operator.
4137
4138    Example:
4139        >>> or_("x=1", or_("y=1", "z=1")).sql()
4140        'x = 1 OR (y = 1 OR z = 1)'
4141
4142    Args:
4143        *expressions (str | Expression): the SQL code strings to parse.
4144            If an Expression instance is passed, this is used as-is.
4145        dialect (str): the dialect used to parse the input expression.
4146        **opts: other options to use to parse the input expressions.
4147
4148    Returns:
4149        Or: the new condition
4150    """
4151    return _combine(expressions, Or, dialect, **opts)

Combine multiple conditions with an OR logical operator.

Example:
>>> or_("x=1", or_("y=1", "z=1")).sql()
'x = 1 OR (y = 1 OR z = 1)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Or: the new condition

def not_(expression, dialect=None, **opts) -> sqlglot.expressions.Not:
4154def not_(expression, dialect=None, **opts) -> Not:
4155    """
4156    Wrap a condition with a NOT operator.
4157
4158    Example:
4159        >>> not_("this_suit='black'").sql()
4160        "NOT this_suit = 'black'"
4161
4162    Args:
4163        expression (str | Expression): the SQL code strings to parse.
4164            If an Expression instance is passed, this is used as-is.
4165        dialect (str): the dialect used to parse the input expression.
4166        **opts: other options to use to parse the input expressions.
4167
4168    Returns:
4169        Not: the new condition
4170    """
4171    this = condition(
4172        expression,
4173        dialect=dialect,
4174        **opts,
4175    )
4176    return Not(this=_wrap_operator(this))

Wrap a condition with a NOT operator.

Example:
>>> not_("this_suit='black'").sql()
"NOT this_suit = 'black'"
Arguments:
  • expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Not: the new condition

def paren(expression) -> sqlglot.expressions.Paren:
4179def paren(expression) -> Paren:
4180    return Paren(this=expression)
def to_identifier(name, quoted=None):
4196def to_identifier(name, quoted=None):
4197    """Builds an identifier.
4198
4199    Args:
4200        name: The name to turn into an identifier.
4201        quoted: Whether or not force quote the identifier.
4202
4203    Returns:
4204        The identifier ast node.
4205    """
4206
4207    if name is None:
4208        return None
4209
4210    if isinstance(name, Identifier):
4211        identifier = name
4212    elif isinstance(name, str):
4213        identifier = Identifier(
4214            this=name,
4215            quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted,
4216        )
4217    else:
4218        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
4219    return identifier

Builds an identifier.

Arguments:
  • name: The name to turn into an identifier.
  • quoted: Whether or not force quote the identifier.
Returns:

The identifier ast node.

def to_interval( interval: str | sqlglot.expressions.Literal) -> sqlglot.expressions.Interval:
4225def to_interval(interval: str | Literal) -> Interval:
4226    """Builds an interval expression from a string like '1 day' or '5 months'."""
4227    if isinstance(interval, Literal):
4228        if not interval.is_string:
4229            raise ValueError("Invalid interval string.")
4230
4231        interval = interval.this
4232
4233    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
4234
4235    if not interval_parts:
4236        raise ValueError("Invalid interval string.")
4237
4238    return Interval(
4239        this=Literal.string(interval_parts.group(1)),
4240        unit=Var(this=interval_parts.group(2)),
4241    )

Builds an interval expression from a string like '1 day' or '5 months'.

def to_table( sql_path: Union[str, sqlglot.expressions.Table, NoneType], **kwargs) -> Optional[sqlglot.expressions.Table]:
4254def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]:
4255    """
4256    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
4257    If a table is passed in then that table is returned.
4258
4259    Args:
4260        sql_path: a `[catalog].[schema].[table]` string.
4261
4262    Returns:
4263        A table expression.
4264    """
4265    if sql_path is None or isinstance(sql_path, Table):
4266        return sql_path
4267    if not isinstance(sql_path, str):
4268        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
4269
4270    catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3))
4271    return Table(this=table_name, db=db, catalog=catalog, **kwargs)

Create a table expression from a [catalog].[schema].[table] sql path. Catalog and schema are optional. If a table is passed in then that table is returned.

Arguments:
  • sql_path: a [catalog].[schema].[table] string.
Returns:

A table expression.

def to_column( sql_path: str | sqlglot.expressions.Column, **kwargs) -> sqlglot.expressions.Column:
4274def to_column(sql_path: str | Column, **kwargs) -> Column:
4275    """
4276    Create a column from a `[table].[column]` sql path. Schema is optional.
4277
4278    If a column is passed in then that column is returned.
4279
4280    Args:
4281        sql_path: `[table].[column]` string
4282    Returns:
4283        Table: A column expression
4284    """
4285    if sql_path is None or isinstance(sql_path, Column):
4286        return sql_path
4287    if not isinstance(sql_path, str):
4288        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
4289    table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2))
4290    return Column(this=column_name, table=table_name, **kwargs)

Create a column from a [table].[column] sql path. Schema is optional.

If a column is passed in then that column is returned.

Arguments:
  • sql_path: [table].[column] string
Returns:

Table: A column expression

def alias_( expression: str | sqlglot.expressions.Expression, alias: str | sqlglot.expressions.Identifier, table: Union[bool, Sequence[str | sqlglot.expressions.Identifier]] = False, quoted: Optional[bool] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts):
4293def alias_(
4294    expression: str | Expression,
4295    alias: str | Identifier,
4296    table: bool | t.Sequence[str | Identifier] = False,
4297    quoted: t.Optional[bool] = None,
4298    dialect: DialectType = None,
4299    **opts,
4300):
4301    """Create an Alias expression.
4302
4303    Example:
4304        >>> alias_('foo', 'bar').sql()
4305        'foo AS bar'
4306
4307        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
4308        '(SELECT 1, 2) AS bar(a, b)'
4309
4310    Args:
4311        expression: the SQL code strings to parse.
4312            If an Expression instance is passed, this is used as-is.
4313        alias: the alias name to use. If the name has
4314            special characters it is quoted.
4315        table: Whether or not to create a table alias, can also be a list of columns.
4316        quoted: whether or not to quote the alias
4317        dialect: the dialect used to parse the input expression.
4318        **opts: other options to use to parse the input expressions.
4319
4320    Returns:
4321        Alias: the aliased expression
4322    """
4323    exp = maybe_parse(expression, dialect=dialect, **opts)
4324    alias = to_identifier(alias, quoted=quoted)
4325
4326    if table:
4327        table_alias = TableAlias(this=alias)
4328        exp.set("alias", table_alias)
4329
4330        if not isinstance(table, bool):
4331            for column in table:
4332                table_alias.append("columns", to_identifier(column, quoted=quoted))
4333
4334        return exp
4335
4336    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
4337    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
4338    # for the complete Window expression.
4339    #
4340    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
4341
4342    if "alias" in exp.arg_types and not isinstance(exp, Window):
4343        exp = exp.copy()
4344        exp.set("alias", alias)
4345        return exp
4346    return Alias(this=exp, alias=alias)

Create an Alias expression.

Example:
>>> alias_('foo', 'bar').sql()
'foo AS bar'
>>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
'(SELECT 1, 2) AS bar(a, b)'
Arguments:
  • expression: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • alias: the alias name to use. If the name has special characters it is quoted.
  • table: Whether or not to create a table alias, can also be a list of columns.
  • quoted: whether or not to quote the alias
  • dialect: the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Alias: the aliased expression

def subquery(expression, alias=None, dialect=None, **opts):
4349def subquery(expression, alias=None, dialect=None, **opts):
4350    """
4351    Build a subquery expression.
4352
4353    Example:
4354        >>> subquery('select x from tbl', 'bar').select('x').sql()
4355        'SELECT x FROM (SELECT x FROM tbl) AS bar'
4356
4357    Args:
4358        expression (str | Expression): the SQL code strings to parse.
4359            If an Expression instance is passed, this is used as-is.
4360        alias (str | Expression): the alias name to use.
4361        dialect (str): the dialect used to parse the input expression.
4362        **opts: other options to use to parse the input expressions.
4363
4364    Returns:
4365        Select: a new select with the subquery expression included
4366    """
4367
4368    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
4369    return Select().from_(expression, dialect=dialect, **opts)

Build a subquery expression.

Example:
>>> subquery('select x from tbl', 'bar').select('x').sql()
'SELECT x FROM (SELECT x FROM tbl) AS bar'
Arguments:
  • expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • alias (str | Expression): the alias name to use.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Select: a new select with the subquery expression included

def column( col: str | sqlglot.expressions.Identifier, table: Union[str, sqlglot.expressions.Identifier, NoneType] = None, schema: Union[str, sqlglot.expressions.Identifier, NoneType] = None, quoted: Optional[bool] = None) -> sqlglot.expressions.Column:
4372def column(
4373    col: str | Identifier,
4374    table: t.Optional[str | Identifier] = None,
4375    schema: t.Optional[str | Identifier] = None,
4376    quoted: t.Optional[bool] = None,
4377) -> Column:
4378    """
4379    Build a Column.
4380
4381    Args:
4382        col: column name
4383        table: table name
4384        schema: schema name
4385        quoted: whether or not to force quote each part
4386    Returns:
4387        Column: column instance
4388    """
4389    return Column(
4390        this=to_identifier(col, quoted=quoted),
4391        table=to_identifier(table, quoted=quoted),
4392        schema=to_identifier(schema, quoted=quoted),
4393    )

Build a Column.

Arguments:
  • col: column name
  • table: table name
  • schema: schema name
  • quoted: whether or not to force quote each part
Returns:

Column: column instance

4396def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast:
4397    """Cast an expression to a data type.
4398
4399    Example:
4400        >>> cast('x + 1', 'int').sql()
4401        'CAST(x + 1 AS INT)'
4402
4403    Args:
4404        expression: The expression to cast.
4405        to: The datatype to cast to.
4406
4407    Returns:
4408        A cast node.
4409    """
4410    expression = maybe_parse(expression, **opts)
4411    return Cast(this=expression, to=DataType.build(to, **opts))

Cast an expression to a data type.

Example:
>>> cast('x + 1', 'int').sql()
'CAST(x + 1 AS INT)'
Arguments:
  • expression: The expression to cast.
  • to: The datatype to cast to.
Returns:

A cast node.

def table_( table, db=None, catalog=None, quoted=None, alias=None) -> sqlglot.expressions.Table:
4414def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table:
4415    """Build a Table.
4416
4417    Args:
4418        table (str | Expression): column name
4419        db (str | Expression): db name
4420        catalog (str | Expression): catalog name
4421
4422    Returns:
4423        Table: table instance
4424    """
4425    return Table(
4426        this=to_identifier(table, quoted=quoted),
4427        db=to_identifier(db, quoted=quoted),
4428        catalog=to_identifier(catalog, quoted=quoted),
4429        alias=TableAlias(this=to_identifier(alias)) if alias else None,
4430    )

Build a Table.

Arguments:
  • table (str | Expression): column name
  • db (str | Expression): db name
  • catalog (str | Expression): catalog name
Returns:

Table: table instance

def values( values: Iterable[Tuple[Any, ...]], alias: Optional[str] = None, columns: Union[Iterable[str], Dict[str, sqlglot.expressions.DataType], NoneType] = None) -> sqlglot.expressions.Values:
4433def values(
4434    values: t.Iterable[t.Tuple[t.Any, ...]],
4435    alias: t.Optional[str] = None,
4436    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
4437) -> Values:
4438    """Build VALUES statement.
4439
4440    Example:
4441        >>> values([(1, '2')]).sql()
4442        "VALUES (1, '2')"
4443
4444    Args:
4445        values: values statements that will be converted to SQL
4446        alias: optional alias
4447        columns: Optional list of ordered column names or ordered dictionary of column names to types.
4448         If either are provided then an alias is also required.
4449         If a dictionary is provided then the first column of the values will be casted to the expected type
4450         in order to help with type inference.
4451
4452    Returns:
4453        Values: the Values expression object
4454    """
4455    if columns and not alias:
4456        raise ValueError("Alias is required when providing columns")
4457    table_alias = (
4458        TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
4459        if columns
4460        else TableAlias(this=to_identifier(alias) if alias else None)
4461    )
4462    expressions = [convert(tup) for tup in values]
4463    if columns and isinstance(columns, dict):
4464        types = list(columns.values())
4465        expressions[0].set(
4466            "expressions",
4467            [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)],
4468        )
4469    return Values(
4470        expressions=expressions,
4471        alias=table_alias,
4472    )

Build VALUES statement.

Example:
>>> values([(1, '2')]).sql()
"VALUES (1, '2')"
Arguments:
  • values: values statements that will be converted to SQL
  • alias: optional alias
  • columns: Optional list of ordered column names or ordered dictionary of column names to types. If either are provided then an alias is also required. If a dictionary is provided then the first column of the values will be casted to the expected type in order to help with type inference.
Returns:

Values: the Values expression object

def var( name: Union[str, sqlglot.expressions.Expression, NoneType]) -> sqlglot.expressions.Var:
4475def var(name: t.Optional[str | Expression]) -> Var:
4476    """Build a SQL variable.
4477
4478    Example:
4479        >>> repr(var('x'))
4480        '(VAR this: x)'
4481
4482        >>> repr(var(column('x', table='y')))
4483        '(VAR this: x)'
4484
4485    Args:
4486        name: The name of the var or an expression who's name will become the var.
4487
4488    Returns:
4489        The new variable node.
4490    """
4491    if not name:
4492        raise ValueError(f"Cannot convert empty name into var.")
4493
4494    if isinstance(name, Expression):
4495        name = name.name
4496    return Var(this=name)

Build a SQL variable.

Example:
>>> repr(var('x'))
'(VAR this: x)'
>>> repr(var(column('x', table='y')))
'(VAR this: x)'
Arguments:
  • name: The name of the var or an expression who's name will become the var.
Returns:

The new variable node.

def rename_table( old_name: str | sqlglot.expressions.Table, new_name: str | sqlglot.expressions.Table) -> sqlglot.expressions.AlterTable:
4499def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
4500    """Build ALTER TABLE... RENAME... expression
4501
4502    Args:
4503        old_name: The old name of the table
4504        new_name: The new name of the table
4505
4506    Returns:
4507        Alter table expression
4508    """
4509    old_table = to_table(old_name)
4510    new_table = to_table(new_name)
4511    return AlterTable(
4512        this=old_table,
4513        actions=[
4514            RenameTable(this=new_table),
4515        ],
4516    )

Build ALTER TABLE... RENAME... expression

Arguments:
  • old_name: The old name of the table
  • new_name: The new name of the table
Returns:

Alter table expression

def convert(value) -> sqlglot.expressions.Expression:
4519def convert(value) -> Expression:
4520    """Convert a python value into an expression object.
4521
4522    Raises an error if a conversion is not possible.
4523
4524    Args:
4525        value (Any): a python object
4526
4527    Returns:
4528        Expression: the equivalent expression object
4529    """
4530    if isinstance(value, Expression):
4531        return value
4532    if value is None:
4533        return NULL
4534    if isinstance(value, bool):
4535        return Boolean(this=value)
4536    if isinstance(value, str):
4537        return Literal.string(value)
4538    if isinstance(value, float) and math.isnan(value):
4539        return NULL
4540    if isinstance(value, numbers.Number):
4541        return Literal.number(value)
4542    if isinstance(value, tuple):
4543        return Tuple(expressions=[convert(v) for v in value])
4544    if isinstance(value, list):
4545        return Array(expressions=[convert(v) for v in value])
4546    if isinstance(value, dict):
4547        return Map(
4548            keys=[convert(k) for k in value],
4549            values=[convert(v) for v in value.values()],
4550        )
4551    if isinstance(value, datetime.datetime):
4552        datetime_literal = Literal.string(
4553            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
4554        )
4555        return TimeStrToTime(this=datetime_literal)
4556    if isinstance(value, datetime.date):
4557        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
4558        return DateStrToDate(this=date_literal)
4559    raise ValueError(f"Cannot convert {value}")

Convert a python value into an expression object.

Raises an error if a conversion is not possible.

Arguments:
  • value (Any): a python object
Returns:

Expression: the equivalent expression object

def replace_children(expression, fun):
4562def replace_children(expression, fun):
4563    """
4564    Replace children of an expression with the result of a lambda fun(child) -> exp.
4565    """
4566    for k, v in expression.args.items():
4567        is_list_arg = isinstance(v, list)
4568
4569        child_nodes = v if is_list_arg else [v]
4570        new_child_nodes = []
4571
4572        for cn in child_nodes:
4573            if isinstance(cn, Expression):
4574                for child_node in ensure_collection(fun(cn)):
4575                    new_child_nodes.append(child_node)
4576                    child_node.parent = expression
4577                    child_node.arg_key = k
4578            else:
4579                new_child_nodes.append(cn)
4580
4581        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)

Replace children of an expression with the result of a lambda fun(child) -> exp.

def column_table_names(expression):
4584def column_table_names(expression):
4585    """
4586    Return all table names referenced through columns in an expression.
4587
4588    Example:
4589        >>> import sqlglot
4590        >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
4591        ['c', 'a']
4592
4593    Args:
4594        expression (sqlglot.Expression): expression to find table names
4595
4596    Returns:
4597        list: A list of unique names
4598    """
4599    return list(dict.fromkeys(column.table for column in expression.find_all(Column)))

Return all table names referenced through columns in an expression.

Example:
>>> import sqlglot
>>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
['c', 'a']
Arguments:
  • expression (sqlglot.Expression): expression to find table names
Returns:

list: A list of unique names

def table_name(table) -> str:
4602def table_name(table) -> str:
4603    """Get the full name of a table as a string.
4604
4605    Args:
4606        table (exp.Table | str): table expression node or string.
4607
4608    Examples:
4609        >>> from sqlglot import exp, parse_one
4610        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
4611        'a.b.c'
4612
4613    Returns:
4614        The table name.
4615    """
4616
4617    table = maybe_parse(table, into=Table)
4618
4619    if not table:
4620        raise ValueError(f"Cannot parse {table}")
4621
4622    return ".".join(
4623        part
4624        for part in (
4625            table.text("catalog"),
4626            table.text("db"),
4627            table.name,
4628        )
4629        if part
4630    )

Get the full name of a table as a string.

Arguments:
  • table (exp.Table | str): table expression node or string.
Examples:
>>> from sqlglot import exp, parse_one
>>> table_name(parse_one("select * from a.b.c").find(exp.Table))
'a.b.c'
Returns:

The table name.

def replace_tables(expression, mapping):
4633def replace_tables(expression, mapping):
4634    """Replace all tables in expression according to the mapping.
4635
4636    Args:
4637        expression (sqlglot.Expression): expression node to be transformed and replaced.
4638        mapping (Dict[str, str]): mapping of table names.
4639
4640    Examples:
4641        >>> from sqlglot import exp, parse_one
4642        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
4643        'SELECT * FROM c'
4644
4645    Returns:
4646        The mapped expression.
4647    """
4648
4649    def _replace_tables(node):
4650        if isinstance(node, Table):
4651            new_name = mapping.get(table_name(node))
4652            if new_name:
4653                return to_table(
4654                    new_name,
4655                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
4656                )
4657        return node
4658
4659    return expression.transform(_replace_tables)

Replace all tables in expression according to the mapping.

Arguments:
  • expression (sqlglot.Expression): expression node to be transformed and replaced.
  • mapping (Dict[str, str]): mapping of table names.
Examples:
>>> from sqlglot import exp, parse_one
>>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
'SELECT * FROM c'
Returns:

The mapped expression.

def replace_placeholders(expression, *args, **kwargs):
4662def replace_placeholders(expression, *args, **kwargs):
4663    """Replace placeholders in an expression.
4664
4665    Args:
4666        expression (sqlglot.Expression): expression node to be transformed and replaced.
4667        args: positional names that will substitute unnamed placeholders in the given order.
4668        kwargs: keyword arguments that will substitute named placeholders.
4669
4670    Examples:
4671        >>> from sqlglot import exp, parse_one
4672        >>> replace_placeholders(
4673        ...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
4674        ... ).sql()
4675        'SELECT * FROM foo WHERE a = b'
4676
4677    Returns:
4678        The mapped expression.
4679    """
4680
4681    def _replace_placeholders(node, args, **kwargs):
4682        if isinstance(node, Placeholder):
4683            if node.name:
4684                new_name = kwargs.get(node.name)
4685                if new_name:
4686                    return to_identifier(new_name)
4687            else:
4688                try:
4689                    return to_identifier(next(args))
4690                except StopIteration:
4691                    pass
4692        return node
4693
4694    return expression.transform(_replace_placeholders, iter(args), **kwargs)

Replace placeholders in an expression.

Arguments:
  • expression (sqlglot.Expression): expression node to be transformed and replaced.
  • args: positional names that will substitute unnamed placeholders in the given order.
  • kwargs: keyword arguments that will substitute named placeholders.
Examples:
>>> from sqlglot import exp, parse_one
>>> replace_placeholders(
...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
... ).sql()
'SELECT * FROM foo WHERE a = b'
Returns:

The mapped expression.

def expand( expression: sqlglot.expressions.Expression, sources: Dict[str, sqlglot.expressions.Subqueryable], copy=True) -> sqlglot.expressions.Expression:
4697def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression:
4698    """Transforms an expression by expanding all referenced sources into subqueries.
4699
4700    Examples:
4701        >>> from sqlglot import parse_one
4702        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
4703        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
4704
4705    Args:
4706        expression: The expression to expand.
4707        sources: A dictionary of name to Subqueryables.
4708        copy: Whether or not to copy the expression during transformation. Defaults to True.
4709
4710    Returns:
4711        The transformed expression.
4712    """
4713
4714    def _expand(node: Expression):
4715        if isinstance(node, Table):
4716            name = table_name(node)
4717            source = sources.get(name)
4718            if source:
4719                subquery = source.subquery(node.alias or name)
4720                subquery.comments = [f"source: {name}"]
4721                return subquery
4722        return node
4723
4724    return expression.transform(_expand, copy=copy)

Transforms an expression by expanding all referenced sources into subqueries.

Examples:
>>> from sqlglot import parse_one
>>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
Arguments:
  • expression: The expression to expand.
  • sources: A dictionary of name to Subqueryables.
  • copy: Whether or not to copy the expression during transformation. Defaults to True.
Returns:

The transformed expression.

def func( name: str, *args, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> sqlglot.expressions.Func:
4727def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
4728    """
4729    Returns a Func expression.
4730
4731    Examples:
4732        >>> func("abs", 5).sql()
4733        'ABS(5)'
4734
4735        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
4736        'CAST(5 AS DOUBLE)'
4737
4738    Args:
4739        name: the name of the function to build.
4740        args: the args used to instantiate the function of interest.
4741        dialect: the source dialect.
4742        kwargs: the kwargs used to instantiate the function of interest.
4743
4744    Note:
4745        The arguments `args` and `kwargs` are mutually exclusive.
4746
4747    Returns:
4748        An instance of the function of interest, or an anonymous function, if `name` doesn't
4749        correspond to an existing `sqlglot.expressions.Func` class.
4750    """
4751    if args and kwargs:
4752        raise ValueError("Can't use both args and kwargs to instantiate a function.")
4753
4754    from sqlglot.dialects.dialect import Dialect
4755
4756    args = tuple(convert(arg) for arg in args)
4757    kwargs = {key: convert(value) for key, value in kwargs.items()}
4758
4759    parser = Dialect.get_or_raise(dialect)().parser()
4760    from_args_list = parser.FUNCTIONS.get(name.upper())
4761
4762    if from_args_list:
4763        function = from_args_list(args) if args else from_args_list.__self__(**kwargs)  # type: ignore
4764    else:
4765        kwargs = kwargs or {"expressions": args}
4766        function = Anonymous(this=name, **kwargs)
4767
4768    for error_message in function.error_messages(args):
4769        raise ValueError(error_message)
4770
4771    return function

Returns a Func expression.

Examples:
>>> func("abs", 5).sql()
'ABS(5)'
>>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
'CAST(5 AS DOUBLE)'
Arguments:
  • name: the name of the function to build.
  • args: the args used to instantiate the function of interest.
  • dialect: the source dialect.
  • kwargs: the kwargs used to instantiate the function of interest.
Note:

The arguments args and kwargs are mutually exclusive.

Returns:

An instance of the function of interest, or an anonymous function, if name doesn't correspond to an existing sqlglot.expressions.Func class.

def true():
4774def true():
4775    """
4776    Returns a true Boolean expression.
4777    """
4778    return Boolean(this=True)

Returns a true Boolean expression.

def false():
4781def false():
4782    """
4783    Returns a false Boolean expression.
4784    """
4785    return Boolean(this=False)

Returns a false Boolean expression.

def null():
4788def null():
4789    """
4790    Returns a Null expression.
4791    """
4792    return Null()

Returns a Null expression.